Superwaba Coding rules

Deprecation policy

borrowed from the Maven project http://maven.apache.org/development/deprecation.html

1. ALL existing class and method modification needs to go through a deprecation phase. We realize that this may make some of the API code look a bit ugly when you look at the source code, but this is a MUST have. It is recommend that developers who deprecate methods move them to the bottom of the .java file.
2. The amount of time between deprecation and removal must be at least one release of your project. It could be more than one version release before the deprecated item is removed, but it cannot be less than one version release. Deprecations should be announced and discussed on the mailing list. By focusing on deprecation through releases, people can choose to code against a specific version of your project and feel comfortable that their code will compile for at least one released version. This also gives people the chance to compile against various previous releases to do incremental upgrades and find out what will break in the next release.
3. Any time a method is deprecated, notification MUST be sent to the developer mailing list documenting the methods that have been deprecated as well as the alternative use. This will allow people to search the archives and find out when and why a method was deprecated as well as the procedure for upgrading to the latest methodology.
4. Items that are not Java code related and cannot be deprecated (such as property key changes and DTD modifications) must be documented on the mailing list.
5. All documentation must be updated at the time of modification to reflect the latest status of the code.
6. Any patches or commits that do not follow these rules will be rejected and it is up to the person who has either checked in the modifications or sent the patch to submit a new patch, fix the problem or back the code out of CVS.

Suggested rules

When changing the signature of a public or protected method or class, this has the potential of breaking someones code who depends on the method or class. Since we are developing Open Source software, there is absolutely no way we can tell if someone is using our code or not. Therefore, in order to minimize the effect of changes, it is possible to use the concept of deprecation. When working on code, keep in mind the following guidelines:

• When modifying an existing public or protected method or class first mark the existing method as deprecated and create a new one to replace the old one.
• Do not remove any public or protected classes/interfaces that have any chance of being used outside of the application. Instead, mark them as deprecated.
• When migrating code from one package to another, deprecate the old package and then have the old code reference the new code as a thin temporary wrapper. The deprecation tells people that the wrapper will be going away at some point in the future.
• Changes to configuration files needs to be well documented so that people can have a laundry list of foo->bar conversions.
• Annotate your changes to the source using the method outlined in Building The VM.