Tài liệu này nhắm đến những người đóng góp cho Bazel.
Nội dung mô tả xác nhận trong Bazel bao gồm một thẻ RELNOTES:, theo sau là một ghi chú phát hành. Nhóm Bazel sử dụng tính năng 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
Nội dung bạn thay đổi 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 cung cấp nội dung tham chiếu đến vấn đề GitHub.
Nếu thay đổi này sẽ thêm / xoá / thay đổi Bazel theo cách mà người dùng thấy được, thì bạn nên đề cập đến thay đổi này.
Nếu có thay đổi lớn, trước tiên, hãy tuân thủ chính sách về tài liệu thiết kế.
Nguyên tắc
Người dùng của chúng tôi sẽ đọc ghi chú phát hành này, vì vậy, ghi chú phải ngắn gọn (tốt nhất là 1 câu), tránh biệt ngữ (thuật ngữ nội bộ tiếng Bazel), nên tập trung vào nội dung thay đổi.
Cung cấp đường liên kết đến tài liệu có liên quan. Hầu hết ghi chú phát hành nào cũng chứa đường liên kết. Nếu phần mô tả đề cập đến cờ, tính năng hoặc tên lệnh, thì có thể người dùng sẽ muốn tìm hiểu thêm về cờ, tính năng hoặc tên lệnh.
Sử dụng dấu ngoặc kép cho mã, biểu tượng, cờ hoặc bất kỳ từ nào có chứa dấu gạch dưới.
Đừng chỉ sao chép và dán nội dung mô tả lỗi. Chúng thường khó hiểu và chỉ có ý nghĩa với chúng tôi và khiến người dùng phải gãi đầu. Mục đích của ghi chú phát hành là giải thích những nội dung 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 nay hỗ trợ Z." Chúng tôi không muốn ghi chú phát hành giống như mục nhập lỗi. Tất cả các mục nhập ghi chú phát hành phải cung cấp nhiều thông tin, đồng thời sử dụng văn phong và ngôn ngữ nhất quán.
Nếu tính năng nào đó không còn được dùng nữa hoặc bị xoá, hãy sử dụng "X đã ngừng hoạt động" hoặc "X đã bị xoá". Không phải là "đã bị xoá" hay "đã bị xoá".
Nếu Bazel hiện thực hiện thao tác khác, hãy sử dụng "X now $newBehavior thay vì $oldBehavior". Điều này cho người dùng biết chi tiết những gì họ 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ợ nội dung 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 nào đó đã bị xoá / không được dùng nữa / thay đổi. Chỉ 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 các bản dựng của họ.
KHÔNG hứa hẹn về các chức năng trong tương lai. Tránh "cờ này sẽ bị xoá" hoặc "việc này sẽ bị thay đổi". Điều này dẫn đến 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 cá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 nào đó.
Quy trình
Trong quy trình phát hà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 thứ trong 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ư của bazel-dev. Những người đóng góp cho Bazel được mời đóng góp cho tài liệu này và đảm bảo những thay đổi của họ được thể hiện chính xác trong thông báo.
Sau đó, thông báo sẽ được gửi lên blog Bazel, sử dụng kho lưu trữ bazel-blog.