In order for people to be comfortable with development of code based on
your project and not have to constantly worry about the rug being pulled
out from underneath them, we have instituted the following policy. Our
goal is to take this matter as an extremely serious practice.
Deprecation Policy Structure
When changing the signature of a public or protected method or class, this
has the potential of breaking someone's code who depends on the method
or class. Since we are developing open source software, we should assume
someone is using our code. Therefore, in order to minimize the effect of
changes, it is possible to use the concept of deprecation. This will respect
the work our users have into their implementations and may encourage users
to maintain their implementations with current versions by having structure
to the process. The following are the rules for reprecation we have:
- 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.
- Discuss depreciations and their reason on the contributors forum documenting
the methods that have been deprecated as well as the alternative use. This
will allow people to search and find out when and why a method was deprecated
as well as the procedure for upgrading to the latest methodology.
- It is recommend that developers who deprecate methods move them to the
bottom of the .java file.
- Any time a method is deprecated, the cvs commit notice should advise of
that there is a deprecation.
- 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. In other words, we can deprecate something in 4.1 and remove it
in the release of 4.2. Discussion will occur on the mailing list and forums
pertaining to the real number of versions between deprecation and removal.
You will have a chance to express your concerns and we will take them into
consideration.
- Items that are not Java code related and cannot be deprecated (such as
property key changes and DTD modifications) must be documented on the contributors
forum.
- All documentation must be updated at the time of modification to reflect the
latest status of the code.
- 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.
Suggestions for following the Depreciation Policy
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.
- When changing a database schema, make sure to provide ALTER TABLE statements
to modify the schema so that people can convert their existing databases easily.
|
