deprecationchecklist

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
deprecationchecklist [2019/11/22 19:16] – WarnerLoshdeprecationchecklist [2020/02/06 16:52] (current) – WarnerLosh
Line 2: Line 2:
  
 There's two processes that the project has found to be workable to deprecate things in %%FreeBSD%%. It's in draft form, but attempts to document, briefly, the current best practices. There's two processes that the project has found to be workable to deprecate things in %%FreeBSD%%. It's in draft form, but attempts to document, briefly, the current best practices.
 +
 +It currently draws too much from the experience of removing obsolete hardware drivers, and should be recast based on the gcc experience, especially for the long process.
  
 ===== Long Process ===== ===== Long Process =====
Line 10: Line 12:
  
 An email to arch@ is usually the first place to start. In this email, spell out the proposal. Spell out both the criteria used to deprecate, as well as the specific components to be removed. If the removal is because the components haven't kept current in terms of APIs, etc, spell out what would be required to keep things in the kernel (eg, the drivers must be properly locked without relying on Giant). The discussion that follows should be done in good faith, with legitimate concerns answered. Include in your plans the placement and MFC of deprecation notices, as described below, if applicable. An email to arch@ is usually the first place to start. In this email, spell out the proposal. Spell out both the criteria used to deprecate, as well as the specific components to be removed. If the removal is because the components haven't kept current in terms of APIs, etc, spell out what would be required to keep things in the kernel (eg, the drivers must be properly locked without relying on Giant). The discussion that follows should be done in good faith, with legitimate concerns answered. Include in your plans the placement and MFC of deprecation notices, as described below, if applicable.
 +
 +In the past, the project's idealized deprecation process would be to deprecate in release X.0 -- done in advance of X.0 being released -- and remove in (X+1).0. This process, however, should be reserved for items in active use, but that none-the-less need to be deprecated. This timeline means the code has to be supported for another 3-5 years, in a supported branch, which comes at a cost to the project, so it should be reserved for extremely disruptive changes to our users.
  
 ===== Short Process ===== ===== Short Process =====
Line 18: Line 22:
  
 If there's more than a few users, it would likely be better to follow the long process above. If not, proceed to implementation. It's better to ask if in doubt. If there's more than a few users, it would likely be better to follow the long process above. If not, proceed to implementation. It's better to ask if in doubt.
 +
 +===== Broken code =====
 +
 +If the code has been broken, and disconnected from the build for a long time (eg, a major release or three), it can usually just be removed w/o notice.
  
 ===== How To Deprecate ===== ===== How To Deprecate =====
  
 Once you've decided it's time to remove, follow the following steps Once you've decided it's time to remove, follow the following steps
-  - Add a notice to the man page. After the SYNOPSIS section, add a new DEPRECATION NOTICE that reads something like "This driver is scheduled for removal prior to the release of %%FreeBSD%% 13.0."+  - Add a notice to the man page. After the SYNOPSIS section, add a new DEPRECATION NOTICE that reads something like "The .nm driver is not present in .Fx 13.0."
   - Add a gone_in(13, "Giant-locked driver"); to the driver's attach routine, or other relevant point. This isn't always possible, but it should only trigger on use if possible.   - Add a gone_in(13, "Giant-locked driver"); to the driver's attach routine, or other relevant point. This isn't always possible, but it should only trigger on use if possible.
   - Make the commit of the above with the Relnotes: yes tag in the commit message.   - Make the commit of the above with the Relnotes: yes tag in the commit message.
Line 29: Line 37:
   - Wait a while (suggested minimum is a week), especially if there's unresolved pushback (or you've scheduled a later removal using the long process)   - Wait a while (suggested minimum is a week), especially if there's unresolved pushback (or you've scheduled a later removal using the long process)
   - svn rm the code and all associated support files and programs.   - svn rm the code and all associated support files and programs.
 +
 +This should be expanded and moved into the handbook.
  
 ===== Notes ===== ===== Notes =====
  • deprecationchecklist.1574450177.txt.gz
  • Last modified: 2019/11/22 19:16
  • by WarnerLosh