wiki:WikiStart/Standards/RG11

Deprecation process in Rock Core

Code

Backward compatibility should not be dropped from packages in rock-core without advance warning.

What needs to be deprecated is obviously left to the package maintainer. However, once a piece of code, or a header (or in Ruby a .rb file) is deprecated, the following constraints should be followed:

  • relevant deprecation warnings must be displayed either at compilation or runtime. The warnings should be present for at least one Rock release cycle, and the deprecation should be noted in the release notes.
  • deprecated code should be kept but disabled for at least one additional release cycle. By "disabled", it is meant that the package's user should have a way to reenable/reuse the code should he decide to do so (as opposed to update its own code). The release notes should mention this.
  • after these two "grace" cycles, the code can be removed at the discretion of the package maintainer. The release notes should mention this.

Packages

NOTE As of 02/2015, this process requires additional features from autoproj (deprecated_package, un-exclusion of packages by adding them to the layout)

Deprecated packages is marked as excluded in the autobuild files using the deprecated_package helper. This helper excludes the package, and adds an exclusion message that mentions deprecation. If the package is deprecated because it is in need of a maintainer, the helper's caller can provide an extra message that mentions it, and how to become the package's maintainer.

Packages excluded this way can be re-added to the build by explicitly mentioning them in the layout. The exclusion message makes this explicit.

Releases that add deprecation should mention it in their release notes.

The package can be removed after a full release cycle. The release notes must mention it.

Last modified 4 years ago Last modified on 02/17/15 18:02:39