all that's written about are Deprecations but there are other API changes apart from Deprecations, right? (e.g. Removals, Behavior Changes, etc.).

A deprecation is not an API change; it's a note on an upcoming API change. Deprecating an API is mandatory before changing it.

I think this whole API section is flawed and would need to be rewritten from scatch:

Messages:

API stability is a great value. Changing an API is a pain for the affected users. We only change an API if the benefit is larget than the pain. This is a careful decision.
Rules
- Deprecations are targeted at the next point-release (i.e. 3.x.0).
- Deprecated API may be removed two point-releases after they were deprecated.
- If in doubt, decisions on API changes are finally made by the API consistency lead developer.
How to deprecate:
- Doc announcement
- Runtime warning (if possible)
- If there is an alternative for the deprecated API, that should already be available during the deprecation period if possible. (I assume that's what the below point was trying to say, but got it mixed up.)

I think this bullet point from the existing docs is wrong:

The deprecated API should, to the maximum extent possible, remain fully functional during the deprecation period. In cases where this is not possible, the deprecation must never make a given piece of code do something different than it was before; at least an exception should be raised.

The old API must remain fully functional during the deprecation period.

a sentence defining deprecation

Ok, I agree that clarity is good. OTOH I'm not too worried here on loosing audience. Generally, If you don't know what a deprecation is, you most likely won't have the experience to estimate the consequences of an API change and should leave this to more experienced people.

Uh oh!

Description

Documentation Link

Problem

Suggested improvement

Matplotlib Version

Matplotlib documentation version

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions