Quy ước changelog

Quy ước changelog

Trang này xác định quy ước mà mọi kho NextPDF công khai tuân theo khi ghi nhận thay đổi và phát hành phiên bản. Đây là tài liệu tham chiếu về quy ước; tài liệu này không xác định hành vi của gói. Ghi chú phát hành theo từng gói và từng phiên bản nằm trong tệp CHANGELOG.md riêng của từng kho. Những quy tắc chung này giúp bản tóm tắt changelog xuyên kho nhất quán và không rò rỉ thông tin.

Conventional Commits 1.0.0

Mọi dòng tiêu đề commit đều dùng type(scope): description. type là một trong các giá trị sau:

Loại	Ý nghĩa	Hướng tới người dùng	Tác động đến phiên bản
feat	Khả năng mới	có	tăng minor
fix	Sửa hành vi	có	tăng patch
perf	Cải thiện hiệu năng mà không thay đổi hành vi	có	tăng patch
refactor	Tái cấu trúc nội bộ không tạo ra thay đổi quan sát được	không	không có
docs	Chỉ tài liệu	không	không có
test	Chỉ kiểm thử	không	không có
build / ci	Chỉ build hoặc pipeline	không	không có
chore	Bảo trì, phụ thuộc hoặc công cụ	không	không có
revert	Hoàn tác một commit trước đó	tùy trường hợp	tùy trường hợp

Thay đổi gây phá vỡ tương thích dùng dấu ! sau loại hoặc phạm vi (feat(api)!: …) hoặc dùng chân trang BREAKING CHANGE:. Cả hai dấu hiệu này đều nâng phiên bản major theo Semantic Versioning. Hãy ghi lại bản sửa liên quan đến bảo mật sao cho bản sửa đó có thể xuất hiện trong cột Security của bản tóm tắt xuyên kho.

Semantic Versioning 2.0.0

Việc tăng phiên bản được xác định theo cơ chế cố định. Một bản phát hành có bất kỳ thay đổi gây phá vỡ tương thích nào là một bản major. Nếu không, bản phát hành có bất kỳ feat nào là một bản minor. Nếu không, bản phát hành có bất kỳ fix hoặc perf nào là một bản patch. Các gói trước 1.0 có thể tăng minor cho thay đổi gây phá vỡ tương thích theo SemVer §4. Commit vẫn mang dấu hiệu phá vỡ tương thích để bản tóm tắt luôn chính xác.

Phân nhóm theo Keep a Changelog

Tệp CHANGELOG.md của từng kho tuân theo Keep a Changelog 1.1.0: các mục được nhóm theo phiên bản đã phát hành và đặt dưới các nhóm Added, Changed, Deprecated, Removed, Fixed và Security. Một mục [Unreleased] có thể chứa các ghi chú đang được thực hiện trong kho, nhưng bản tóm tắt xuyên kho chỉ tính các phiên bản đã gắn thẻ và đã phát hành. Công việc chưa phát hành không bao giờ xuất hiện trong chỉ mục công khai.

Cách suy ra bản tóm tắt xuyên kho (và giữ bản tóm tắt không rò rỉ thông tin)

Bảng tóm tắt trên chỉ mục changelog được tạo bằng cách đọc lịch sử Conventional Commits của từng kho tại thẻ phát hành mới nhất ở chế độ chỉ đọc, rồi đếm các danh mục. Các quy tắc suy ra được cố ý giới hạn chặt để chi tiết nội bộ không lọt ra ngoài:

1. Số đếm, không phải nội dung. Chỉ báo cáo số lượng commit theo từng loại hướng tới người dùng. Không hiển thị dòng tiêu đề, phần thân, chân trang hay mã băm nào của commit.
2. Chỉ các loại hướng tới người dùng. docs, test, ci, chore và refactor bị loại trừ vì chúng không thay đổi điều gì mà người dùng của gói có thể quan sát được.
3. Chỉ những bản đã phát hành. Một commit chỉ được tính sau khi commit đó trở thành một phần của bản phát hành đã gắn thẻ của một gói công khai.
4. Không có định danh nào. Các tham chiếu nội bộ tới issue, ticket, chu kỳ, đợt hoặc hạng mục công việc có thể xuất hiện trong phạm vi commit riêng tư sẽ không bao giờ được hiển thị ra ngoài, vì bản thân phần văn bản phạm vi không bao giờ được hiển thị. Chỉ loại được đọc.
5. Không ghi nhận đóng góp tự động. Các dòng trailer ghi nhận tự động của người đóng góp không được đọc hay hiển thị.

Vì vậy, changelog công khai là bản tóm tắt theo danh mục kèm liên kết tới tệp CHANGELOG.md riêng của từng gói, chứ không phải nguồn cấp commit tổng hợp. Bản tóm tắt được thiết kế ngay từ đầu để không rò rỉ thông tin nội bộ. Nội dung phát hành chính thức luôn nằm cùng gói sở hữu nội dung đó.

Xem thêm

• Changelog
• Quy ước cho công thức tích hợp
• Conventional Commits 1.0.0
• Semantic Versioning 2.0.0