Enforce the use of `deprecated-removed` in docs
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 77.2k
- Forks
- 36k
- PR merge metrics
- PR metrics pending
Description
In the docs we have two directives that can be used to document deprecations: deprecated and deprecated-removed.
I think we should always prefer the latter:
- it will make it easier to track and document removals
- it will give people a target, so they can plan around it
Even if the removal version gets postponed, it's better to postpone than to say that something is deprecated and then just remove it at an unspecified time in the future.
Currently deprecated is more commonly used:
$ grep -r 'deprecated::' --include=*.rst | wc -l
226
$ grep -r 'deprecated-removed::' --include=*.rst | wc -l
30
- set removal version for deprecated features using
deprecated-removed - automate the documentation of deprecations (see also #92308)
- possibly deprecate the
deprecateddirective and replace it withdeprecated-removed
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by rerunning the documented grep counts for deprecated:: and deprecated-removed:: across the .rst files, then review the related work in #92308. The issue's checklist indicates that completion would require setting removal versions, considering automation, and deciding whether to deprecate the older directive.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100