python / python/cpython

Enforce the use of `deprecated-removed` in docs

オープン
#92,564 コメント 12 件 リアクション 2 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

3.10 3.11 3.12 3.9 (EOL) docs type-feature
主要言語
Python
スター
77.2k
フォーク
36k
平均マージ
1日 9時間
マージ済み PR(30日)
558

説明

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 deprecated directive and replace it with deprecated-removed

コントリビューションガイド

コントリビューションガイドを開く

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

調査の方向性

まず、.rst ファイル全体で deprecated::deprecated-removed:: の文書化された grep 件数を再実行して確認し、その後 #92308 の関連作業を確認します。Issue のチェックリストは、完了するには削除バージョンを設定し、自動化を検討し、古いディレクティブを非推奨にするかどうかを決定する必要があることを示しています。

索引モデルが issue の本文から書いたものです。

評価

領域
documentation
issue の種類
ドキュメント
難易度
5/5
見積もり時間
1週間以上
活発さ
停滞
明瞭さ
説明が足りない
初心者へのやさしさ
25/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。