python / python/cpython

Replace deprecation lists in whatsnew files with tables

未關閉
#122,652 2 則留言 2 個 reaction 已指派 0 人 在 GitHub 檢視

還沒有人認領這個 Issue。

docs
主要語言
Python
星號
77.2k
分支
36k
PR 合併指標
PR 指標待擷取

描述

Documentation

The whatsnew files currently contain lists of removals, deprecations, and pending removals (see e.g. https://docs.python.org/3.13/whatsnew/3.13.html#new-deprecations). These tables are not particularly easy to navigate and take enough space (~1/3?) that they make the whatsnew itself difficult to navigate too.

I would consider replacing them with one or more tables.

The columns could include:

  1. the deprecated/removed API (which links to the API itself using :func:/:class:/:meth:/etc.)
  2. the version where the deprecation was introduced
  3. the version where the API is/will be removed (not needed if we have a separate table for each version)
  4. a link to the PR that introduced the deprecation
  5. possibly the contributor

The table won't contain the full description that explains why it was deprecated and how to replace it, making the table more compact and easier to navigate than the list we currently have. This will also saves us from (near) duplicating the description in both the .. deprecated:: directive in the modules pages and in the whatsnew.

Most deprecated APIs are seldomly used and don't affect many users. If they do, they are probably just a small fraction of all the deprecations, so all the text in the list is not particularly useful. It's also easier to run the code and see the deprecation warnings/errors or quickly scan a table than scanning a long list of deprecations.

The table is still convenient for checking if anything I'm using has been deprecated, for ctrl+f'ing deprecated APIs as I'm fixing them, for finding links to the APIs, and for reviewing the versions where they will be removed.

Some notes about using tables:

  • Some deprecation require short description (e.g. "Passing more than one positional argument to sqlite3.connect()"). There are possible solutions to this:
    • don't elaborate further and just link to the API that contains the deprecation notice
    • have a column for the "affect API" and a "note" column where to add a short description (if needed)
    • only use the tables for deprecated APIs, leaving the rest as a list
  • The name/link to the API already contains the module name, but a separate column for the module might be easier to read
  • If we have different tables depending on the version the APIs is being removed, then we won't need a column for it.
  • Like the lists, the tables can be included in multiple whatsnew files using include files (see #122085)

(cc @hugovk, @AA-Turner, @encukou)

貢獻指南

開啟貢獻指南

從這裡開始

  1. 先讀完整個 Issue,再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫,在一個分支上完成修改。
  4. 送出 Pull Request,並在描述裡引用這個 Issue 編號。

研究方向

首先檢視 whatsnew 檔案中的 deprecation、removal 和 pending-removal 清單,包括 3.13 頁面,並研究 #122085 中所引用的 include-file 作法。完成的標準是就表格結構達成共識,並在保留必要描述、API 連結和版本資訊的同時一致地套用該結構。

由索引模型根據 Issue 內容生成。

評估

技術堆疊
python
領域
documentation
Issue 類型
文件
難度
5/5
預估耗時
一週以上
活躍度
停滯
描述清晰度
需要釐清
新手友好度
25/100

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。