Because Confluence doesn't have an official API yet, you should assume that any change you make to manager interfaces, model objects, services, or really any commonly used code will in some way impact third-party plugin developers. As such, we should always be careful to deprecate, rather than remove old functionality.
Because we want to keep third-party developers happy, we should deprecate methods that may be used by plugins instead of just deleting them. However, deprecated methods pollute the namespace, and keeping them around indefinitely just encourages people to continue to use them.
Therefore, we should record when a method has been deprecated, and before each major release we should remove anything that has stayed deprecated for more than six months or two major versions (whichever is longer).
The use of the
@Deprecated annotation also allows runtime tooling to discover and alert about deprecated method usage.
For a simple redirect, the deprecation tag is the only Javadoc the method should require. Developers should consult the doc for the linked alternative to find out more about what the method is likely to do:
For a "this is no longer the right way to do things" deprecation, a longer explanation may be required, and the old Javadoc may need to be retained for developers who are still stuck doing things the old way for some reason. A short explanation is put in the deprecated tag itself, and the detail is put in the main body of the Javadoc:
Note that implementations of deprecated methods will result in compile warnings if they are not also marked as deprecated.
Fix Confluence Code to Avoid Deprecated Usage
When deprecating a class or method in Confluence, you must remove the majority – if not all – of the usages of that class or method throughout Confluence. If you don't have the time or inclination to do so, you should probably not deprecate the method.
This makes sure that our own code doesn't violate our own deprecation unnecessarily, and also provides a sanity check for whether you should deprecate something or not. If it is used too many times inside Confluence to begin changing, it could well be the same for external code and you should think hard about deprecating such a frequently used method.
When Not to Deprecate
In some situations, maintaining deprecated methods may be impossible. For example:
You should never deprecate when...
- The underlying model has changed, rendering any client of the old code obselete. For example if you move from
List getPermissions(), the former method would return dangerously incorrect information if it were maintained, and thus should be deleted.
- The old way of doing things is dangerous. For example, if
userManager.getAllUsers()is being removed because it kills the server, we should not feel guilty forcing plugins to upgrade to the safe way of doing things.
You should make a judgement call when...
- There would be significant effort required to maintain parallel, deprecated way of doing things for six months
- You would be forced to write an ugly API because all the "right" method/class names are taken up with deprecated methods (assume the new way of doing things will stick around forever)