I believe we’re mixing two aspects here.

• when doing an API migration (“use this instead of that”) it can be helpful to have a version in which both APIs exists without without warning. This helps to write code that does not emit warnings and supports multiple versions without explicit version gating. It’s primarily helping downstream libraries who can’t aggressively pin matplotlib to recent releases.
• pending deprecations are specifically about heads-up notifications to downstream libraries, so that they can update their cod. A user should typically not see a deprecation from a library, because they cannot fix it (other than updating to a new library version, which requires the library author to know about the deprecation before it’s regularly raised.)

There’s an overlap between the two, but they are not identical. For example, one could/should raise a pending depreciation warning for API removals.

Overall, the question of pending depreciations and migrations with a non-raising intermediate version is a trade off between how smooth the transition should be and how much effort and migration time we want to invest.

I haven’t completely thought this through. Some aspects to consider:

• Nightly builds are an alternative way to give an heads-up. They can party replace pending depreciations. But that’s something typically only larger projects do. Also with that mechanism, changes should not be introduced in right before a release, because that reduces reaction time.
• Sometimes we may just/or additionally notify “known users” if they are limited. Think: projections -> cartopy or rarely used APO -> GitHub code search results
• The procedure may also depend on the expected frequency of use. It may be ok if users see a warning from a not—commonly used function in seaborn, but it’s not ok if we make every function of the current seaborne release emit a warning.
• It can also depend on whether it’s just a cleanup (longer transitions are feasible) or it’s an enabler for upcoming changes (we don’t want to wait too long to introduce them)
• I’ve not competently thought through all migration aspects for downstream libs: How does their release schedules and matplotlib version requirements strategy interplay with above deprecation strategies? Does the combination still deliver on the intended goals?

This has to be thought through carefully, otherwise we may complicate and delay our depreciations and thus the ability to improve without adding substantial benefit.

Overall, our current way of working seems not too bad. At least I’m not aware of complaints. We’re doing transition versions and pending depreciations on a case-by-case basis. It’s reasonable to document that they exist and what they are for, with a suggestion when to use them. But roughly, I don’t have the feeling we need to use them more often.

When exactly to use pending deprecations is a complex topic, see#29375 (review). To move forward and not get stuck on details, I suggest to leave out the exact definition on when we apply pending deprecations for now.