Deprecation Policy

Whether for APIs or end-user functionality, deprecation should follow a general pattern of flagging and then allowing time for community adaptation. Only after an appropriate time has passed should the deprecated element be removed. The appropriate amount of time will be determined by the case, but a standard measure should be in terms of feature releases - eg. it may be flagged as deprecated for 2.7 and then removed in 2.8.

What counts as appropriate flagging may also vary with the case. Purely technical method deprecation may be handled in the code itself, but deprecation of user-facing functionality should be prominently flagged in the release notes and announced on-list. The deprecated functionality should be disabled by a configuration property that the local institution may override. If the deprecated functionality is an entire tool, it should simply be stealthed.

Deprecation decisions should be arrived at by consensus, and it will be the responsibility of the product council to document these outcomes or help forge this consensus where needed, though in matters of code maintenance the maintenance team should generally be deferred to.

Reasons for deprecation may include:

• The functionality or code is no longer maintainable, or there are outstanding critical or blocker issues and no community resource is able to help
• The functionality or code has been superseded by code or capabilities which meet the same requirements in an improved way (according to the consensus view), and the improvement has been demonstrated in production with a full release cycle

Deprecation decisions should happen during the same period in which new tools or capabilities are being considered for inclusion, and both before QA begins for a given release.

NB. If a blocker arises for a new capability during a QA cycle, and no one is available to fix it, the offending code may be simply removed. This is not deprecation.