The deprecation notice should be merged to stable/11.

https://www.freebsd.org/doc/en/articles/committers-guide/rules.html section 17.4.

In D14890#313049, @gjb wrote:

The deprecation notice should be merged to stable/11.

https://www.freebsd.org/doc/en/articles/committers-guide/rules.html section 17.4.

That is my plan and the sole purpose of this change.

In D14890#313052, @brooks wrote:

In D14890#313049, @gjb wrote:

The deprecation notice should be merged to stable/11.

https://www.freebsd.org/doc/en/articles/committers-guide/rules.html section 17.4.

That is my plan and the sole purpose of this change.

The change states "will be removed in 12.0" for a commit presumably to head. Will it be updated post-MFC to stable/11 to reflect it had been removed?

In D14890#313057, @imp wrote:

I'm cool either way with tense.
Almost makes me think we need a mandoc macro :)
Almost.

I'm mainly (mostly) making sure I understand to which branch this will be committed.

I would argue for a direct removal of the support in head, and a direct commit to stable/11 noting the deprecation.

Or maybe just "The .Nm driver is not present in .Fx 12.0 and later."

In D14890#313061, @emaste wrote:

I think the tense is fine - in an ideal world we would have committed this just before 11 branched, giving release users (on 11) and -current users a full cycle before the drivers actually get removed just before the 12 branch. Of course lacking a time machine that's not possible, but committing this to head, merging to stable/11 asap, and removing from 12-current at your convenience is probably the best approximation.

While that would be ideal, I'd wager a moderate amount that neither one of these printfs ever fires, nor would have had it been in 11.0 (or even 9.0).

In D14890#313063, @emaste wrote:

Or maybe just "The .Nm driver is not present in .Fx 12.0 and later."

But presumably the manual page for the driver still exists in the version that does not have the driver?

I could do a direct commit if that's preferred. My preference

In D14890#313065, @gjb wrote:

In D14890#313063, @emaste wrote:

Or maybe just "The .Nm driver is not present in .Fx 12.0 and later."

But presumably the manual page for the driver still exists in the version that does not have the driver?

At the moment, all versions have the driver. Once I do the removal CURRENT won't have the driver or the manpage. I was planning to commit to current, MFC, and then do the removal.

In D14890#313066, @brooks wrote:

I could do a direct commit if that's preferred. My preference

In D14890#313065, @gjb wrote:

In D14890#313063, @emaste wrote:

Or maybe just "The .Nm driver is not present in .Fx 12.0 and later."

But presumably the manual page for the driver still exists in the version that does not have the driver?

At the moment, all versions have the driver. Once I do the removal CURRENT won't have the driver or the manpage. I was planning to commit to current, MFC, and then do the removal.

I believe historically we have removed <foo> from head, then did a direct commit to stable, since the MFC is irrelevant at this point. You would just be adding an extra step (and a 3-day timer) to the MFC.

My view is, go with the commit to head to remove the driver, and do a direct commit to stable/11 marking the deprecation as is in your patch.

The argument for adding the notice in HEAD and then MFCing it is so that when someone wants to do the next deprecation, for 13.0, and searches the tree they'll find an example to copy.

In D14890#313069, @emaste wrote:

The argument for adding the notice in HEAD and then MFCing it is so that when someone wants to do the next deprecation, for 13.0, and searches the tree they'll find an example to copy.

I'd prefer this as well. It's more "regular" and better order in the tree. Direct commits to stable branches should be greatly discouraged without a good reason... and this isn't a good reason.... We don't have to remove the drivers on an emergency basis, so a 3 day MFC period in a non-freeze situation is totally fine.

In D14890#313064, @imp wrote:

While that would be ideal, I'd wager a moderate amount that neither one of these printfs ever fires, nor would have had it been in 11.0 (or even 9.0).

I'm not taking the other side of that bet :)

In D14890#313072, @imp wrote:

In D14890#313069, @emaste wrote:

The argument for adding the notice in HEAD and then MFCing it is so that when someone wants to do the next deprecation, for 13.0, and searches the tree they'll find an example to copy.

I'd prefer this as well. It's more "regular" and better order in the tree. Direct commits to stable branches should be greatly discouraged without a good reason... and this isn't a good reason.... We don't have to remove the drivers on an emergency basis, so a 3 day MFC period in a non-freeze situation is totally fine.

Sorry, I don't agree with the logic here. The workflow here, as suggested, is:

• Commit a deprecation notice to head with a 3-day MFC timeout for something that will be removed (and subsequently, the deprecation notice commit is just noise)
• Merge the deprecation notice to the affected branch(es) after waiting 3 days, unnecessarily
• Effectively revert the original commit in head in the *real* commit to remove what is now deprecated

This does not make sense to me.

Direct commits happen to stable branches, although not regularly, but somewhat often for things that -- wait for it -- have been removed from head.

Why not, instead, properly document a sensible workflow for these things in the commmitters guide. This eliminates any confusion regarding a previous comment about looking through revision history.

Direct commits happen to stable branches, although not regularly, but somewhat often for things that -- wait for it -- have been removed from head.

But it hasn't been removed from head yet. Adding a deprecation notice in a stable branch after something is already removed from head is really an artifact of the fact that we've poorly managed the deprecation process in the past.

An idealized deprecation workflow would add the notice in CURRENT as soon as we know something will be removed from the next major release (or, is at risk of being removed if a maintainer does not step up), and MFC the notice to stable branches, and then remove the driver / functionality just prior to the stable branch for the next release. This allows the maximum amount of time/notice for users to adapt, step up to maintain an abandoned driver, etc.

We can't do anything about the first part for the drivers in this review. For the second part I'd probably still argue for keeping these until just before stable/12 is branched although as @imp points out these are drivers we probably should have deorbited in 10 or 11 already.

It makes perfect sense to me: put the deprecation notice out now. No need to wait. Merge it after 3 days. Then, sometime later, maybe a lot later, remove the files. There's no confusion about commit or anything. We don't know how long the removal might be delayed for reasons that may arise during reviews of the actual removal. It decouples the two things: we declare our intention to remove it now. Later we remove it. We might declare our intention on a lot of things, over several months, then delete them all at once. We've done that in mailing lists and such, and it would be better to record the intention right away. If some reason comes up, we can always back it out And it doesn't usually come up right away, but often later.

Anyway, it's totally logical to me, given the last decade I've had removing things from the tree. It sometimes isn't a straight line, and often times is a twisty path. I doubt arcnet or FDDI will be an issue, and might get removed right away, but we don't want to document the simple case because you can't predict, a priori, what people will get upset about and what they won't. Better to document the deprecation and merge, if needed, separate from the removal.

In D14890#313075, @emaste wrote:

Direct commits happen to stable branches, although not regularly, but somewhat often for things that -- wait for it -- have been removed from head.

But it hasn't been removed from head yet. Adding a deprecation notice in a stable branch after something is already removed from head is really an artifact of the fact that we've poorly managed the deprecation process in the past.

An idealized deprecation workflow would add the notice in CURRENT as soon as we know something will be removed from the next major release (or, is at risk of being removed if a maintainer does not step up), and MFC the notice to stable branches, and then remove the driver / functionality just prior to the stable branch for the next release. This allows the maximum amount of time/notice for users to adapt, step up to maintain an abandoned driver, etc.

We can't do anything about the first part for the drivers in this review. For the second part I'd probably still argue for keeping these until just before stable/12 is branched although as @imp points out these are drivers we probably should have deorbited in 10 or 11 already.

Ok, I'll bite - *when* is the removal expected to happen?

Note that head gets significantly less end-user testing (and implicitly less usage) than stable, which gets less usage than releng branches.

What exactly is the target user base for committing a deprecation notice for something that will be removed next week, for example?

Ok, I'll bite - *when* is the removal expected to happen?

Sometime before stable/12 branches. If there's no compelling reason to do otherwise (i.e., these drivers are not holding up other work), then just before stable/12 branches.

In D14890#313080, @gjb wrote:

In D14890#313075, @emaste wrote:

Direct commits happen to stable branches, although not regularly, but somewhat often for things that -- wait for it -- have been removed from head.

But it hasn't been removed from head yet. Adding a deprecation notice in a stable branch after something is already removed from head is really an artifact of the fact that we've poorly managed the deprecation process in the past.

An idealized deprecation workflow would add the notice in CURRENT as soon as we know something will be removed from the next major release (or, is at risk of being removed if a maintainer does not step up), and MFC the notice to stable branches, and then remove the driver / functionality just prior to the stable branch for the next release. This allows the maximum amount of time/notice for users to adapt, step up to maintain an abandoned driver, etc.

We can't do anything about the first part for the drivers in this review. For the second part I'd probably still argue for keeping these until just before stable/12 is branched although as @imp points out these are drivers we probably should have deorbited in 10 or 11 already.

Ok, I'll bite - *when* is the removal expected to happen?

Note that head gets significantly less end-user testing (and implicitly less usage) than stable, which gets less usage than releng branches.

What exactly is the target user base for committing a deprecation notice for something that will be removed next week, for example?

In this case I'll probably do the removal in the next few weeks. I'll start prepping the commits soon, but they are a background task and require universe runs so will take a while.

The target is users who are paying attention to -current or -stable commits. The point here is to indicate intent at least a little in advance. The main reason to commit to CURRENT first as a matter of course is that we aren't very good to actually following through on things we said we'd remove (see the jail config variables warning) and I'd like to leave breadcrumbs indicating our intent.

We've had a few of these in the past that were like "no, I use that, and here's the fixed driver, so don't kill it." But the vast majority have been silence, or "please give me time to fix it" and there's no fix forthcoming. By announcing the intent on multiple mailing lists, and in the repo, different classes or sets of users notice. Saying 'hey, we'll remove this' and then choosing not to because of feedback is nicer on the repo than killing it then a commit unkilling it later.

We've only done direct commits to stable when it was a "oops, I've already removed the driver from head and forgot to do the deprecation notice". In general we should just follow the rule of HEAD first.

If we had a real policy we would probably require some amount of time between adding deprecation notices and actual removal (e.g. requiring the deprecation notice in stable for a release at least), but right now we have a lot of cruft in the tree due to not doing purges regularly which means there's pressure to remove faster. An actual policy would probably entail going through head after branching a new stable/X (or even just before branching) to add notices on code we think is stale and unused. Once a release or two with the notice has gone out and we haven't gotten any negative feedback, then the code would be purged from head. In that world you definitely want the deprecation notices in head.