Tài liệu này dành cho những người đóng góp cho Bazel.
Nội dung mô tả thay đổi trong Bazel bao gồm thẻ RELNOTES:, theo sau là ghi chú phát hành. Nhóm Bazel sử dụng công cụ 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 tham chiếu đến vấn đề trên GitHub.
Nếu thay đổi thêm / xoá / thay đổi Bazel theo cách người dùng có thể thấy, thì bạn nên đề cập đến thay đổi đó.
Nếu thay đổi là đáng kể, trước tiên, hãy làm 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ú phải ngắn gọn (tốt nhất là một câu), tránh sử dụng thuật ngữ chuyên môn (thuật ngữ nội bộ của Bazel), tập trung vào nội dung thay đổi.
Đưa vào đường liên kết đến tài liệu có liên quan. Hầu hết ghi chú phát hành đều phải chứa một đườ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ì có thể người dùng sẽ muốn biết thêm về nội dung đó.
Sử dụng dấu nháy đơn xung quanh mã, ký hiệu, cờ hoặc bất kỳ từ nào chứa dấu gạch dưới.
Đừng chỉ sao chép và dán nội dung mô tả lỗi. Các thông báo lỗi này thường khó hiểu và chỉ có ý nghĩa với chúng ta, khiến người dùng phải vò đầu bức tai. Ghi chú phát hành dùng để giải thích những gì đã 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 hiện hỗ trợ Y" hoặc "X hiện hỗ trợ Z". Chúng tôi không muốn ghi chú phát hành giống như mục lỗi. Tất cả các mục nhập ghi chú phát hành phải cung cấp thông tin và sử dụng cùng một kiểu và ngôn ngữ.
Nếu một nội dung nào đó không còn được dùng nữa hoặc bị xoá, hãy sử dụng cụm từ "X không còn được dùng nữa" hoặc "X đã bị xoá". Không phải "đã bị xoá" hoặc "đang bị xoá".
Nếu Bazel hiện làm gì đó khác đi, hãy sử dụng "X hiện là $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 tính năng nào đó, hãy sử dụng "Bazel hiện hỗ trợ/không còn hỗ trợ X".
Giải thích lý do một nội dung bị xoá / ngừng hoạt độ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ọ.
ĐỪNG đưa ra bất kỳ lời hứa nào về chức năng trong tương lai. Tránh sử dụng cụm từ "cờ này sẽ bị xoá" hoặc "cờ này sẽ 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 ta không muốn họ bắt đầu lo lắng về việc các bản dựng hiện tại của họ bị lỗi vào một thời điểm nào đó.
Quy trình
Trong quy trình phát hành, chúng ta thu thập các thẻ RELNOTES của mỗi thay đổi. Chúng ta sao chép mọi thứ 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 sẽ gửi email đến danh sách gửi thư bazel-dev. Các cộng tác viên Bazel được mời đóng góp vào tài liệu này 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 về Bazel bằng cách sử dụng kho lưu trữ bazel-blog.