Enforce the use of `deprecated-removed` in docs
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
- Issue type
- Documentation
- Clarity
- Needs clarification
- Activity status
- Stale
- Domain
- documentation
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.
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
- Dominant language
- Python
- Stars
- 77.2k
- Forks
- 36k
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 558
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.
More from python/cpython
-
docs pending
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
stdlib type-feature
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
stdlib type-feature
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
build type-bug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
stdlib topic-email type-feature
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
bancolombia/sentinel#23 ·
-
test md OpenCI
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
-
integration:quickjs org:external priority:backlog topic:code-interpreter topic:middleware type:feature
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
langchain-ai/deepagents#6450 ·
-
bug client
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100