Expand deprecation classes and review deprecation policy

[browniebroke]

Description

We're got the need for introducing gradual deprecation in 2 PRs recently:

• Use 'results' key in TemplateHTMLRenderer when data is a list #9972
• Add a compatibility setting for ListSerializer error formats #10027

Which made me realise there was a gap:

• We have a deprecation policy documenting some deprecation classes which have been removed from the codebase
• Explaining contributors how to use these to add new deprecations wasn't documented
• No explanations on how to surface these deprecations from our users

This PR aims to close these gaps so that the other work in flight can make use of these deprecations instead of introducing new API surface tangentially related to the fix.

[Copilot]

🟡 Changes recommended

The new documentation contains incorrect/outdated warning class names and a pytest pyproject.toml section header that would mislead users and contributors when applying the guidance.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR formalizes and documents DRF’s deprecation warning classes for the current release cycle, including stable alias names for downstream warning filtering, and expands contributor/release documentation around how to introduce and surface deprecations.

Changes:

• Added RemovedInDRF319Warning and two “current cycle” alias warning names in rest_framework/deprecation.py.
• Expanded deprecation policy docs to describe the alias warnings and how to surface them in test runs.
• Added contributor and release-process guidance for adding/rotating deprecations.

File summaries

File	Description
rest_framework/deprecation.py	Adds the missing RemovedInDRF319Warning and introduces stable alias names for filtering warnings across releases.
docs/community/release-notes.md	Documents the alias warnings and provides guidance on surfacing deprecations in pytest.
docs/community/project-management.md	Updates the release checklist to include rotating deprecation warnings.
docs/community/contributing.md	Adds contributor workflow documentation for introducing and testing deprecations.

Review details

Suppressed comments (5)

docs/community/contributing.md:179

• The import in this example references RemovedInDRF32Warning, but the actual warning class is RemovedInDRF320Warning (as defined in rest_framework/deprecation.py).

    from rest_framework.deprecation import RemovedInDRF32Warning

docs/community/contributing.md:184

• The warning category in this example should match the imported class (RemovedInDRF320Warning), otherwise the snippet won’t run as written.

        RemovedInDRF32Warning,

docs/community/contributing.md:204

• The admonition example says the feature will be removed in DRF 3.2, but the rest of this section’s example is describing removal in 3.20.

        The `foo` argument is deprecated and will be removed in DRF 3.2. Use `bar` instead.

docs/community/contributing.md:207

• This removal-process example still refers to the old 3.1/3.2/3.3 warning class names; updating it to the current warning classes keeps the guidance consistent with rest_framework/deprecation.py.

Removing a deprecated feature is the mirror image, and happens as part of the release process. When 3.1 is released, everything raising a `RemovedInDRF31Warning` is deleted, along with the class itself and the documentation of the deprecated behavior, `RemovedInDRF32Warning` is escalated to subclass `DeprecationWarning`, a fresh `RemovedInDRF33Warning` is added for the next cycle's deprecations, and the two aliases are moved on to point at them.

docs/community/contributing.md:196

• This example uses RemovedInDRF32Warning, but the warning class in the codebase is RemovedInDRF320Warning (as defined in rest_framework/deprecation.py).

    with pytest.warns(RemovedInDRF32Warning, match="Use `bar` instead"):

• Files reviewed: 4/4 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[peterthomassen]

Looks good, thanks!

• The DRF 3.0, 3.1 etc. release numbers in the explanatory text seem to be examples. I thnk that's fine; let's not switch to current numbers (would be quickly outdated, too). But, add "for example" (I added an in-line comment).
• Other Copilot feedback seems valid.
• Took me a while to understand the point of RemovedInNextDRFVersionWarning, but it's about surfacing in the test suite. Perhaps add a comment where those classes are defined that this is used for testing (currently sounds like unused / theoretical third-party use).

[browniebroke]

• Took me a while to understand the point of RemovedInNextDRFVersionWarning, but it's about surfacing in the test suite. Perhaps add a comment where those classes are defined that this is used for testing (currently sounds like unused / theoretical third-party use).

Yes, it's mirroring what Django does and is more for users of DRF, to control how they surface warning without having to keep updating heir filters as they upgrade, as explained here: https://github.com/browniebroke/django-rest-framework/blob/794355194b175c4173bd90f594cddddff1a488ef/docs/community/release-notes.md#surfacing-deprecations-in-your-test-suite

[browniebroke]

• The DRF 3.0, 3.1 etc. release numbers in the explanatory text seem to be examples. I thnk that's fine; let's not switch to current numbers (would be quickly outdated, too). But, add "for example" (I added an in-line comment).

• Other Copilot feedback seems valid.

I wonder if I should make this more explicit by NOT using v3 as major, and instead use e.g. v1 🤔