Document the workflow for deprecating something in CPython.

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

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

  • #1469 của @Lincoln-developer — đã đóng, không merge

Đánh giá

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

Hướng nghiên cứu

Bắt đầu bằng việc xem xét workflow được đề xuất trong issue này, tài liệu Porting và tệp pending-removal-in....rst, bao gồm cả Sphinx role deprecated-removed. Phần việc hoàn thành cần ghi lại quyết định deprecation, cảnh báo và hướng dẫn porting, thời điểm loại bỏ, quy trình feedback và cách xử lý các deprecation không có ngày loại bỏ cố định.

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

Mô tả

Describe the enhancement or feature you'd like
Document the workflow on how to deprecate something in CPython.
Deprecating something in Python involves raising deprecation warning and then actually removing the code some time later (at least 2 release cycles). We don't have this process documented clearly.

Describe alternatives you've considered
Currently this is undocumented process, and each of us has to just figure it out somehow.

Additional context
Discussed on Discord core-workflow-and-bots channel, and now opening a ticket based on the discussions.

Basic process:

  • An issue was opened calling for deprecation of something
  • We deprecate the code by adding warnings.deprecated (or warnings._deprecated)
  • Document the deprecation. Needs a Porting doc (how?)
  • The issue can be closed after the code for adding deprecation has been merged. It doesn't need to stay open for 2+ more years.
  • Add the deprecation to the pending-removal-in....rst file
  • At the scheduled removal year, open a new issue for the removal
  • Finally remove the code

Other info:

  • Some deprecations don't have set removal date.
  • There are also deprecated-removed Sphinx role to help advertise the removal dates.
  • How to decide whether Removal/Deprecation is the right solution?
    • search the usage, search on GitHub, grep, check PyPI projects to get an idea of the widespread usage
    • when searching, look not just if people are using it, but how they're using it. Document the use case for the porting notes
  • Is there a template for deprecation warning message?
  • Should have documentation about how to port/replace it (porting notes)
  • Users are encouraged to give feedback about deprecation by filing an issue

Note there is an open proposal for extending the removal of deprecated code to 5 years instead of 2.

Ngôn ngữ chính
Python
Star
2.1k
Fork
1k
Merge trung bình
2 ngày 12 giờ
Pull request đã merge (30 ngày)
12

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.

Issue khác của python/devguide

Tất cả issue của python/devguide

Issue tương tự

Thêm issue về Python

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.