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 bản 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à ghi
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. Năn nỉ cung cấp 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 dễ thấy cho người dùng, thì có thể bạn nên đề cập đến nó.
Nếu có sự thay đổi lớn, hãy làm theo tài liệu thiết kế đầu tiên.
Nguyên tắc
Người dùng của chúng tôi sẽ đọc ghi chú phát hành đó nên phải ngắn gọn (tốt nhất là một ghi chú ), tránh biệt ngữ (thuật ngữ nội bộ Bazel), nên tập trung vào những gì thay đổi sắp xảy ra.
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 chứa một liên kết. Nếu phần mô tả đề cập đến cờ, tính năng, tên lệnh, người dùng có thể sẽ muốn biết thêm về ứng dụng đó.
Sử dụng dấu ngoặc kép 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.
Đừ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 vò đầu gáy. Ghi chú phát hành là giải thích những gì đã thay đổi và lý do thay đổi bằng ngôn từ dễ hiểu.
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 có Z." Chúng tôi không muốn ghi chú phát hành giống như mục nhập lỗi. Toàn bộ bản phát hành nội dung ghi chú cần giàu thông tin, đồng thời sử dụng văn phong và ngôn ngữ nhất quán.
Nếu một 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á" hoặc "đã bị xoá".
Nếu Bazel hiện thực hiện điều gì đó khác đi, hãy sử dụng "X now $newBehavior" thay vì $oldBehavior" (Hành vi trước) ở thì hiện tại. Điều này cho người dùng biết chi tiết những gì cần khi họ 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. Một câu là đủ, nhưng chúng ta 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ề các chức năng trong tương lai. Tránh "cờ này sẽ đã bị xoá" hoặc "điều này sẽ được 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ẽ tự hỏi là "khi nào?" và chúng tôi không muốn họ bắt đầu lo lắng về bản dựng hiện tại của họ bị lỗi vào thời điểm không xác định.
Quy trình
Trong bản phát hành
,
chúng tôi sẽ thu thập thẻ RELNOTES của mỗi cam kết. Chúng tôi sao chép mọi thứ trong tệp Google
Tài liệu
nơi chúng tôi xem xét, chỉnh sửa và sắp xếp các ghi chú.
Trình quản lý phát hành gửi email đến 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 phản ánh chính xác trong thông báo.
Sau đó, thông báo sẽ được gửi đến Bazel blog của chúng tôi bằng cách sử dụng thẻ bazel-blog kho lưu trữ.