python / python/cpython

Replace deprecation lists in whatsnew files with tables

Đang mở
#122,652 2 bình luận 2 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

docs
Ngôn ngữ chính
Python
Star
77.2k
Fork
35.9k
Chỉ số merge pull request
Chỉ số pull request đang chờ

Mô tả

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)

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Hướng nghiên cứu

Bắt đầu bằng cách xem xét các danh sách deprecation, removal và pending-removal trong các tệp whatsnew, bao gồm cả trang 3.13, đồng thời kiểm tra cách tiếp cận include-file được tham chiếu trong #122085. Được xem là hoàn tất khi đã thống nhất về cấu trúc bảng và áp dụng cấu trúc đó một cách nhất quán, đồng thời giữ lại các mô tả cần thiết, các liên kết API và thông tin phiên bản.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
python
Lĩnh vực
documentation
Loại issue
Tài liệu
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Cần làm rõ
Mức phù hợp với người mới
25/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.