Deprecation Checklist

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

For items that may still be in use, or whose users need notice of removal, the long process should be used.

Since each situation is different, here's a summary of what one should generally do, though the project defines no required process, though any process should weigh the costs to our users against the benefit to the developers.

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

There are some little-used obsolete drivers in the tree that can safely just be removed. However, you should follow the following process to do so to allow for people that are using the driver a short window to speak up. For example, ISA SCSI cards that have no DMA ability and weren't that popular when new could follow this process. Drivers for classic PCI (not PCI Express) devices likely can fall into this category too. I'll assume we're removing some hardware thing, but the same concepts could apply.

First, you should find out when the cards were made and popular, and how popular they were when new. Next, you should use on-line available resources to determine if the cards are still in use. There's not a lot of data around, but the nycbug group has a dmesg cache that's you can gather information from. There is a reasonable cross section in http://dmesgd.nycbug.org/, but it does tend to be biased to the unusual, so some care needs to be taken with the data. If the hardware in question hasn't been reported in the last 6-8 years (2-3 major releases), that's a good candidate to follow this process. If it has been mentioned, judgement should be used to see how popular it remains and weigh that against the costs of maintaining the driver.

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

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 "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.
Make the commit of the above with the Relnotes: yes tag in the commit message.
Optionally send an email to stable@ announcing the deprecation.
MFC the code (it's ok not to wait the normal 3 days unless we're in a freeze)
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.

This should be expanded and moved into the handbook.

Notes

Since the decision to deprecate support can be difficult, one should weigh the costs to our users against the costs of maintaining something in the tree. If the cost is low, one might be biased to keeping something around in the face of even little use. If the costs are high, the threshold to keep may be higher (and include correcting the technical defects, if possible, that motivated the removal).