Đang ghi ghi chú phát hành

Báo cáo sự cố Xem nguồn

Tài liệu này dành cho cộng tác viên Bazel.

Thông tin 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ông tin 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 đề liên quan đến GitHub.

  • Nếu thay đổi này có tác dụng thêm / xoá / thay đổi Bazel theo cách người dùng thấy được, thì việc đề cập đến thay đổi đó có thể là một lợi thế.

Nếu thay đổi đáng kể, trước tiên, hãy làm theo chính sách thiết kế tài liệu.

Nguyên tắc

Người dùng của chúng tôi sẽ đọc ghi chú phát hành, vì vậy, bạn nên viết ngắn gọn (tốt nhất là một câu), tránh dùng biệt ngữ (thuật ngữ nội bộ Bazel) nên tập trung vào nội dung thay đổi.

  • Bao gồm một đườ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 đườ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ì có thể người dùng sẽ muốn biết thêm về nội dung đó.

  • 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 chứa dấu gạch dưới.

  • Khô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, khiến người dùng phải cào đầu. Mục đích của ghi chú phát hành là giải thích những gì đã thay đổi và lý do tại sao người dùng lại hiểu được ngôn ngữ đó.

  • Luôn sử dụng thì hiện tại và định dạng "Bazel hiện hỗ trợ Y" hoặc "X giờ đây có hỗ trợ Z". Chúng tôi không muốn bản ghi chú phát hành của mình nghe giống như các 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 và dùng văn phong cũng như 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 không còn được dùng nữa" hoặc "X đã bị xoá". Không bị "đã loại bỏ" hoặc "đã bị xóa".

  • Nếu Bazel hiện đang làm gì đó khác biệt, hãy sử dụng "X now $newBehavior thay vì $oldBehavior" trong thì hiện tại. Điều này cho người dùng biết chi tiết nội dung mong đợi 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 hỗ trợ X nữa".

  • Giải thích lý do một nội dung nào đó bị xoá / không dùng nữa / đã 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 đến các bản dựng của họ.

  • KHÔNG đưa ra bất kỳ lời hứa nào về chức năng trong tương lai. Tránh "cờ này sẽ bị xóa" hoặc "điều 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 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 bị hỏng vào lúc không xác định.

Quy trình

Trong quy trình phát hành, chúng tôi sẽ thu thập các thẻ RELNOTES của mọi thay đổi. Chúng tôi sao chép mọi thứ trong Tài liệu Google nơi chúng tôi xem xét, chỉnh sửa và sắp xếp các ghi chú.

Người quản lý bản phát hành sẽ gửi một email đến danh sách gửi thư của bazel-dev. Cộng tác viên 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 này sẽ được gửi tới blog của Brazil bằng cách sử dụng kho lưu trữ blog blog.