Tài liệu này dành cho những người đóng góp cho Bazel.
Nội dung mô tả cam kết trong Bazel bao gồm một thẻ RELNOTES: theo sau là ghi chú phát hành. Nhóm Bazel sử dụng thẻ này để theo dõi các thay đổi trong mỗi bản phát hành và viết thông báo phát hành.
Tổng quan
Thay đổi của bạn có phải là bản sửa lỗi không? Trong trường hợp đó, bạn không cần ghi chú phát hành. Vui lòng thêm thông tin tham chiếu đến vấn đề trên GitHub.
Nếu thay đổi thêm / xoá / thay đổi Bazel theo cách mà người dùng có thể thấy, thì bạn nên đề cập đến thay đổi đó.
Nếu thay đổi đó quan trọng, trước tiên, hãy tuân theo chính sách về tài liệu thiết kế.
Nguyên tắc
Người dùng sẽ đọc ghi chú phát hành, vì vậy, ghi chú này phải ngắn gọn (tốt nhất là một câu), tránh dùng thuật ngữ chuyên môn (thuật ngữ nội bộ của Bazel) và tập trung vào nội dung thay đổi.
Thêm đường liên kết đến tài liệu có liên quan. Hầu như mọi ghi chú phát hành đều phải có đường liên kết. Nếu nội dung mô tả đề cập đến một cờ, một tính năng, một tên lệnh, thì người dùng có thể sẽ muốn biết thêm về nội dung đó.
Sử dụng dấu nháy ngược xung quanh mã, biểu tượng, cờ hoặc bất kỳ từ nào có chứa dấu gạch dưới.
Không chỉ sao chép và dán nội dung mô tả lỗi. Nội dung mô tả lỗi thường khó hiểu và chỉ có ý nghĩa đối với chúng tôi, khiến người dùng cảm thấy bối rối. Ghi chú phát hành nhằm giải thích những thay đổi và lý do thay đổi bằng ngôn ngữ mà người dùng có thể hiểu được.
Luôn sử dụng thì hiện tại và định dạng "Bazel now supports Y" (Bazel hiện hỗ trợ Y) hoặc "X now does Z" (X hiện thực hiện Z). Chúng tôi không muốn ghi chú phát hành của mình nghe giống như mục nhập lỗi. Tất cả mục nhập ghi chú phát hành đều phải cung cấp thông tin và sử dụng kiểu cũng như ngôn ngữ nhất quán.
Nếu một nội dung nào đó đã bị ngừng sử dụng hoặc bị xoá, hãy sử dụng "X has been deprecated" (X đã bị ngừng sử dụng) hoặc "X has been removed" (X đã bị xoá). Không sử dụng "is removed" (đã bị xoá) hoặc "was removed" (đã bị xoá).
Nếu Bazel hiện thực hiện một nội dung nào đó theo cách khác, hãy sử dụng "X now $newBehavior instead of $oldBehavior" (X hiện $newBehavior thay vì $oldBehavior) ở thì hiện tại. Điều này giúp người dùng biết chi tiết những gì họ có thể mong đợi khi sử dụng bản phát hành mới.
Nếu Bazel hiện hỗ trợ hoặc không còn hỗ trợ một nội dung nào đó, hãy sử dụng "Bazel now supports / no longer supports X" (Bazel hiện hỗ trợ/không còn hỗ trợ X).
Giải thích lý do một nội dung nào đó đã bị xoá / ngừng sử dụng / thay đổi. Một câu là đủ, nhưng chúng tôi muốn người dùng có thể đánh giá tác động đối với bản dựng của họ.
KHÔNG hứa hẹn về chức năng trong tương lai. Tránh sử dụng "this flag will be removed" (cờ này sẽ bị xoá) hoặc "this will be changed" (nội dung này sẽ bị thay đổi). Điều này gây ra sự không chắc chắn. Điều đầu tiên người dùng sẽ thắc mắc là "khi nào?" và chúng tôi không muốn họ bắt đầu lo lắng về việc bản dựng hiện tại của họ bị hỏng vào một thời điểm không xác định.
Quy trình
Trong quá trình phát hành
quy trình,
chúng tôi thu thập các thẻ RELNOTES của mọi cam kết. Chúng tôi sao chép mọi nội dung vào một Google
Tài liệu
để xem xét, chỉnh sửa và sắp xếp các ghi chú.
Trình quản lý bản phát hành gửi email đến danh sách gửi thư bazel-dev. Những người đóng góp cho Bazel được mời đóng góp vào tài liệu và đảm bảo rằng các thay đổi của họ được phản ánh chính xác trong thông báo.
Sau đó, thông báo sẽ được gửi đến blog Bazel, bằng cách sử dụng kho lưu trữ bazel-blog.