Tapestry is being used by a increasingly large community of developers and it is necessary that they have some stability in their development.

To that end, classes and methods must follow a developer-friendly lifecycle. If a method or class must be deleted, it should be marked as deprecated in one minor release, and can be removed in the following minor release.

For example, a method may be marked as deprecated in release 2.2-alpha-1. This change isn't considered "real" until release 2.2. The method can be removed any time after that, say in release 2.3-alpha-3, and the removal becomes "real" in release 2.3.

Don't simply mark a method as deprecated, give the end-developer the information needed adapt their code. Use the following template as part of the Javadoc comment:

  @deprecated To be removed in Version.
    Use {@link SomeClass#someMethod(...)} instead.

It is also important for the changer to make the transition as simple as possible for the end-developer. Base classes and default implementations should be changed to make use of the new API in such as way that, at most, a recompile of the end-developer's classes is required.

Sometimes, changes require a lack of backwards compatibility. If a method has to change and the old signature can't be maintained, then simply change it ... but be sure to document the change in the Tapestry release notes (web/new.html).