Note: This is under discussion and is not finalized
To allow graceful evolution of the public Cytoscape API in order to manage plugin compatibility, we need to follow the following process for any public API change that will potentially break existing plugins (e.g. class name change, package change, method signature change, etc.)
- Create shiny new functionality
- Deprecate dusty, dented old functionality
Modify JavaDoc of old functionality to alert users that
- They must switch to new functionality at their earliest convenience
- They have one year to do this as the old functionality will be removed after "Sep.29.2006". We list the actual date in the javadocs so that we know when we can remove it.
- Replace all uses of old functionality in core with new functionality to set a good example.
- Remove all references to old functionality from public documentation - the docs still exist, but should never be accessed.
- Note: Code should not be deprecated except when following this process.
If a user asks, if Cytoscape supports something from the old interface, we must answer 'no'. In reality the functionality will exist, but is not advertised and old plugins won't break for at least 1 year.
Evolution of the public APIs is necessary, but this process will allow us to manage the required changes and to adequately communicate with our users so that they can manage and plan their own code appropriately when changes need to be made.
Reference: http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/deprecation/deprecation.html