API Guidelines

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.

Extending existing APIs

When a new method is to be added to an API, the following procedure should be followed in order to minimize immediate impact, as well as to give a clean path forward for updating the API.

API Extension Procedure

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 new interface, with 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 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 interface can be removed, and the functionality can be moved into the existing interface (and those class(es) that implement it).