Page Comparison

UNDER CONSTRUCTION

Introduction

Pentaho's public application programming interfaces (APIs) form a programming contract between Pentaho and Embed customers, plugin developers, and community contributors. Therefore it is very important that proper procedures are followed anytime API methods are changing or being removed.

...

1. If there is no existing JIRA case that provoked the API change request, create a JIRA case proposing the extension.
   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. Implementation of extension to interface XYZ
   1. Create a new child interface called XYZExtended (if it does not already exist) that extends XYZ, add the new method(s) to XYZExtended.
   2. Where the existing method is called, add an "instanceof" check looking for the new interface. If true, cast and delegate. If not, retain the current behavior.
   3. @Deprecate the existing new interface, with lots of detail in the javadoc detailed javadoc saying that the methods will be added to the existing interface at the next major release (see the guidelines here)
   4. Document the new interface, usage, deprecation of the old, etc. in the appropriate locations
4. If there's there’s agreement to proceed, make the change.
5. The architect should then work with PM and other stakeholders to determine how long the deprecated features should be supported. In the case of API changes this is often until the next major release.
6. 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

...

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

...

/**
 * @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();

...

/**
 * @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 : Code Blockjavascriptjavascript

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

   Functions Code Blockjavascriptjavascript

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

    interface can be removed, and the functionality can be moved into the existing interface (and those class(es) that implement it).