Tài liệu này dành cho người đóng góp của Bazel.
Nội dung mô tả xác nhận trong Bazel bao gồm một thẻ RELNOTES:, theo sau là ghi chú phát hành. Nhóm Bazel sử dụng API này để theo dõi các thay đổi trong từng 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à một 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 đính kèm tệp tham chiếu đến vấn đề trên GitHub.
Nếu sự thay đổi này thêm / xoá / thay đổi Bazel theo cách mà người dùng nhìn thấy, thì bạn nên đề cập đến điều này.
Nếu có thay đổi đá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át hành phải ngắn gọn (tốt nhất là một câu), tránh sử dụng biệt ngữ (thuật ngữ nội bộ Bazel), 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 như mọi ghi chú phát hành đều phải chứa đường liên kết. Nếu nội dung mô tả đề cập đến cờ, tính năng, tên lệnh, thì người dùng có thể sẽ muốn biết thêm về tính năng đó.
Sử dụng dấu ngoặc kép xung quanh mã, ký hiệu, cờ hoặc từ bất kỳ có 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 này thường mơ hồ và chỉ có ý nghĩa với chúng tôi và khiến người dùng gáy đầu. Ghi chú phát hành có mục đích 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 hiện hỗ trợ Z". Chúng tôi không muốn ghi chú phát hành của mình nghe có vẻ giống như mục nhập lỗi. Tất cả các mục ghi chú phát hành phải cung cấp nhiều thông tin, đồng thời có phong cách và ngôn ngữ nhất quán.
Nếu tính năng nào đó không đượ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 "đã bị xóa" hay "đã bị xóa".
Nếu Bazel hiện hành động theo cách khác, hãy sử dụng "X ngay $newBehavior thay vì $oldBehavior" ở thì hiện tại. Điều này cho phép người dùng biết chi tiết những điều cần 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ợ 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 nội dung nào đó bị xoá / ngừng sử dụng / 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 bản dựng của họ.
KHÔNG đưa ra bất kỳ hứa hẹn nào về 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 mang đến sự bất ổ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 bị hỏng vào một thời điểm không xác định.
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 lệnh xác nhận. Chúng tôi sao chép mọi thứ trong Tài liệu
Google để xem lại, chỉnh sửa và sắp xếp 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 trên 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 tới blog của Bazel bằng cách sử dụng kho lưu trữ blog bazel.