Deprecation Guidelines

Introduction

Pentaho's software is designed to be extended and customized. This is not only allowed-for, it's encouraged! Therefore it is very important that proper deprecation procedures are followed anytime features of the system are changing or being removed.

Deprecation Procedure

1. Create a JIRA case proposing the deprecation.
   1. If relevant, provide links to the superseding APIs in the Jira case.
   2. Assign the case to the governing architect.
2. Send notification of the case to the team leads / architects involved with the affected project.
3. If there’s agreement to proceed, make the change.
4. The architect should then work with PM and other stakeholders to determine how long the deprecated features should be supported.
5. Keep the case open and set the fix version for the next major release when there's agreement that the deprecated features can be removed

General Guidelines

1. Deprecated features need to continue to work!!
2. Tests involving the deprecated features must not be removed. If there are superseding features, they need to be tested in addition to the deprecated ones.
3. Deprecated items should be preserved until the next major release at the least.

Java Deprecation

1. Use both the @Deprecated annotation on the affected Class / Method / Field to generate compiler warnings, as well as @deprecated inside the javadoc comment
2. There should be a short sentence immediately following the @deprecated javadoc tag explaining when and why it’s deprecated.

   /**
    * @deprecated As of release 6.0, use {@link Clazz#method()} instead
    **/
   void verify();
   

3. Optionally, if there needs to be more description, the paragraph following @deprecated will also be associated with the deprecation tag and presented appropriately in the Javadoc

   /**
    * @deprecated As of release 6.0, no longer needed.
    * Calls to verify will do nothing as of the 5.1 release. Verification happens as part of the connect
    * method. You can safely remove these calls
    **/
   void verify();
   

4. If the replacement API usage is not as simple as a method/class name change covered by a {@link}, then the paragraph following the @deprecated tag should include a code snippet showing the new API usage.

   /**
    * @deprecated As of release 6.0.
    * This class has been replaced by the non-blocking version {@link foo.Clazz}
    * Usage:
    * <pre>
    *   Clazz newClass = Clazz.newInstance();
    *   Future future = newClass.doSomethingInteresting();
    * </pre>
    **/
   void OldClazz();
   

Service Deprecation

Enunciate will use the Javadoc comments in its generated documentation.

1. The deprecated service methods should log at the WARN level to alert system admins of deprecated service usage

Javascript Deprecation

1. console.warn the deprecated modules / functions with comments similar to Javadoc. Reference the replacements where possible.
2. AMD Modules
   Warn inside the define not outside, so it flags actual usage vs loading :

   define( 'common-ui/someModule', function(){
     console.warn( "Deprecated: as of 6.0. Use the common-ui/BetterOne module instead." )
     return { ... }
   }
   

3. Functions

   function pentahoGet(){
     console.warn( "Deprecated: pentaho-ajax.js#pentahoGet is deprecated as of 6.0. Use the 'dojo/Request' module instead." )
   }