Thêm thông tin thay đổi vào ghi chú phát hành

BeeWare Docs Tools sử dụng towncrier để hỗ trợ việc soạn thảo ghi chú phát hành cho mỗi bản phát hành. Khi bạn gửi yêu cầu pull, yêu cầu đó phải bao gồm một ghi chú thay đổi - ghi chú thay đổi này sẽ trở thành mục trong ghi chú phát hành mô tả những thay đổi đã được thực hiện.

Mỗi yêu cầu kéo (pull request) phải bao gồm ít nhất một tệp trong thư mục changes/ chứa mô tả ngắn gọn về thay đổi được thực hiện bởi yêu cầu kéo đó. Ghi chú thay đổi phải ở định dạng Markdown, trong một tệp có tên theo định dạng <id>.<fragment type>.md. Nếu thay đổi bạn đề xuất nhằm sửa lỗi hoặc triển khai tính năng đã có số vấn đề (issue number) tương ứng, thì ID sẽ là số của phiếu đó. Nếu thay đổi không có vấn đề tương ứng, số PR có thể được sử dụng làm ID. Bạn sẽ không biết số PR này cho đến khi đẩy yêu cầu kéo, do đó lần chạy CI đầu tiên sẽ không qua được kiểm tra towncrier; hãy thêm ghi chú thay đổi và đẩy bản cập nhật PR, sau đó CI sẽ chạy thành công.

Có năm loại đoạn văn:

• feature: Bản PR bổ sung một tính năng hoặc khả năng mới mà trước đây chưa có (ví dụ: bổ sung hỗ trợ cho một định dạng gói mới, hoặc một tính năng mới trong một định dạng gói hiện có);
• bugfix: Bản cập nhật này khắc phục một lỗi trong phiên bản hiện tại;
• doc: Bản tin báo chí là một bước cải tiến đáng kể đối với tài liệu;
• removal; Bản PR này mang lại một thay đổi không tương thích ngược trong API BeeWare Docs Tools; hoặc
• misc; Một thay đổi nhỏ hoặc mang tính hành chính (ví dụ: sửa lỗi chính tả, làm rõ một chi tiết ngôn ngữ nhỏ hoặc cập nhật phiên bản phụ thuộc) mà không cần phải thông báo trong ghi chú phát hành.

Mô tả trong ghi chú thay đổi này nên là một bản tóm tắt "tiếp thị" ở cấp độ cao về thay đổi đó từ góc độ của người dùng, chứ không phải là một mô tả kỹ thuật chuyên sâu hay chi tiết triển khai. Nó khác biệt với thông điệp cam kết (commit message) – thông điệp cam kết mô tả những gì đã được thực hiện để các nhà phát triển sau này có thể theo dõi lý do đằng sau một thay đổi; trong khi đó, ghi chú thay đổi là mô tả dành cho người dùng, những người có thể không am hiểu về cơ chế hoạt động bên trong.

Ví dụ: nếu bạn sửa một lỗi liên quan đến việc đặt tên dự án, nội dung thông báo cam kết có thể như sau:

Áp dụng quy tắc kiểm tra biểu thức chính quy nghiêm ngặt hơn để không cho phép tên dự án bắt đầu bằng số.

Ghi chú thay đổi tương ứng sẽ có nội dung như sau:

Tên dự án không được bắt đầu bằng số nữa.

Một số yêu cầu kéo (PR) có thể giới thiệu nhiều tính năng và sửa nhiều lỗi, hoặc đưa ra nhiều thay đổi không tương thích ngược. Trong trường hợp đó, PR có thể có nhiều tệp ghi chú thay đổi. Nếu bạn cần liên kết hai loại ghi chú thay đổi với cùng một ID, bạn có thể thêm một hậu tố số. Ví dụ: nếu PR 789 thêm một tính năng được mô tả trong ticket 123, khắc phục một lỗi được mô tả trong ticket 234, và cũng thực hiện hai thay đổi không tương thích ngược, bạn có thể có 4 tệp ghi chú thay đổi:

• 123.feature.md
• 234.bugfix.md
• 789.removal.1.md
• 789.removal.2.md

Để biết thêm thông tin về towncrier và các loại đoạn tin, hãy xem Đoạn tin tức. Bạn cũng có thể xem các ví dụ hiện có về đoạn tin tức trong thư mục changes của kho lưu trữ BeeWare Docs Tools. Nếu thư mục này trống, có thể là do BeeWare Docs Tools vừa phát hành một phiên bản mới; các tệp ghi chú thay đổi sẽ bị xóa và hợp nhất để cập nhật ghi chú phát hành với mỗi phiên bản. Bạn có thể xem tệp đó để biết kiểu bình luận được yêu cầu; bạn có thể xem các PR được hợp nhất gần đây để biết cách định dạng ghi chú thay đổi của mình.