The main rule is to do not introduce any changes that are backwards incompatible. That is, existing client applications and plug-ins should continue to run in the next release of BASE, without the need to change them. It may sound easy but there are many things to watch out for. There is a great article about this subject on http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs.
- The Public API
-
Not all code in BASE is considered to be part of the public API. See Section 29.1, “The Public API of BASE” and the javadoc for information about the public API. Changes made to the internal API does not have to follow the same rules.
- Binary compatibility
-
This is hardest requirement and means that existing binaries must run with the updated BASE version. The Eclipse document discusses this type of compatibility in great detail.
- Contract compatibility
-
Methods should continue to do things in the same ways as before. Avoid introducing side-effects and expanding/contracting the allowed range of return or parameter values. This may not always be easy to keep this type of compatibility. For example, adding a new option to an enumeration may break code that is not prepared for it.
- Internal data structure compatibility
-
It may not be possible to keep the internal data structures. If they change the update script should convert the old data to the new format. Avoid exposing the internal data structure to client applications. Use wrapper classes, etc, to hide as much as possible.
- Source code compatibility
-
This is not an important issue and in most cases the problems are easy to fix.
![[Important]](../gfx/admonitions/important.png) |
Do not forget to log changes! |
|---|---|
|
Any change that may affect backwards compatibility must be logged in Appendix I, API changes that may affect backwards compatibility. |