I would suggest targeting v3.10.x with a removal directly, and main with a change from 3.10 to 3.11.

Do we also need to remove the changenotes?
https://github.com/matplotlib/matplotlib/blob/main/doc/api/next_api_changes/deprecations/28074-TS.rst
https://github.com/matplotlib/matplotlib/blob/main/doc/api/next_api_changes/deprecations/27998-TS.rst

@ksunden do you have a link to the issue?

This is a fundamental problem with deprecations. When you introduce a deprecation third-party libraries will see it. This will have two effects:

• The tests of the library will pick up the warning. Libraries have to version-gate to silence the warning. This seems the current motivation.
• Users will see the warning without being able to do something about it as soon as we release, because the code is in the third-party library and they did not have time to react/release.

I believe that you cannot reasonably circumvent version gating in third party libraries. Even if we give one release of transition where both versions are available equally, they have to pin matplotlib quite aggressively. It's rather the second point that motivates me for pending releases.

By default, we currently do not do pending deprecations. Is that something we should should regularly do and add to our API change guideline? OTOH I'm not aware of substantial complaints on our current deprecation strategy.

Assuming pandas is following SPEC0, does this mean we should wait until May 2026 (drop date for mpl3.9 support) to deprecate the old parameter?

This was discovered by the run of Fedora builds that @QuLogic did, rather than being specifically reported/having an issue to link to.

I discussed it with @tacaswell and we came to the decision to delay it by just one release, which still may incur version gates on libraries, but minimizes impact to especially downstream applications (which tend to have narrower support windows). If the new API were available previously, I would be less worried about it, even if a version without fell within Pandas' minimal support window, since the further downstream effects are minimized.

As for release notes, I will take that on in release, not including them in the compiled form and leaving them in next... But thanks for the reminder there.

I would like to give one version with both the old and new way not warning before we warn on the old way to reduce the impact of the transition.

What got me with this one is that use are something like:

def.plot.some_plotting_method(..., vert=True)

where pandas is just passing kwargs through to us so no library changes are needed to pandas (and I do not think they should be smoothing out this change and doing the translation from vert to orientation!) so the impact is probably going to predominately fall on individual users (not on the libraries) who are typing this out interactively or in notebooks. Given that and the rough guess that day-to-day working environments tend to fluctuate +/- 1 in terms of versions of packages delaying the deprecation warning one release increases the number of users who can switch to the new way and never think about it again.

The tests need updating to match the changes here.

Coming back to the general question: Do we need to refine our deprecation policy? e.g.

The suggested alternative must be available one release prior to deprecation. If the alternative has just been added, do a pending deprecation for one release and switch to the actual depreaction in the subsequent release.

I'm overall not clear what we want. The comments and code here and in #29159 send mixed signals

a. 3.10: discourage, 3.11: deprecate
b. 3.10: discourage, 3.11: pending deprecate
c. 3.10: pending deprecate, 3.11: deprecate

I would have expected c.

I was largely thinking a) discourage in 3.10, deprecate in 3.11.

A pending deprecation still does fail Pandas tests, so if we find "don't break pandas with our release" motivating, that doesn't solve that issue.

As far as I understand #29155 (comment). The failure of pandas test should come from the way the pandas test code is written not from the pandas code itself. That's an important difference because then users of pandas don't rave to wait for a pandas release. In other words, pandas can right now change their tests to fix this - yes this requires version gating to get a smooth transition, but pandas has a Minimum Version CI run (currently using Matplotlib 3.6) and unless they aggressively pin to 3.10 in the future they'll have to do version gating anyway.

On plus side, other libraries would become aware through the pending deprecation.

The failure of pandas test should come from the way the pandas test code is written not from the pandas code itself.

That is also my understanding and I agree that pandas putting version gating in their tests is not a big deal.

That's an important difference because then users of pandas don't rave to wait for a pandas release.

However, if we add the new way and deprecate the old way in one step we are going to inflict version gating on user's code which I think is a problem.

That's why

However, if we add the new way and deprecate the old way in one step we are going to inflict version gating on user's code which I think is a problem.

That's why I suggested a pending deprecation. Users should not see these.

That's why I suggested a pending deprecation. Users should not see these.

Ok, then I think we agree! I get lost in the details of what warnings users do/do not see under what situations.

@ksunden will do a independent PR to 3.10.x and handle the (likely) conflicts on the merge-up.