Để xem tài liệu về bản phát hành ổn định, vui lòng sử dụng trình đơn thả xuống "Tài liệu được tạo phiên bản". Chế độ xem mặc định phản ánh phiên bản mới nhất ở HEAD.

Trang này được dịch bởi Cloud Translation API.

Hướng dẫn triển khai các thay đổi có thể gây lỗi

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

Chúng ta không thể tránh khỏi việc thực hiện những thay đổi có thể gây lỗi đối với Bazel. Chúng tôi sẽ phải thay đổi thiết kế và khắc phục những chỗ không hoạt động tốt. Tuy nhiên, chúng tôi cần đảm bảo rằng cộng đồng và hệ sinh thái Bazel cũng có thể tuân theo những nguyên tắc đó. Để đạt được mục tiêu đó, dự án Bazel đã áp dụng chính sách về khả năng tương thích ngược. Tài liệu này mô tả quy trình để những người đóng góp Bazel thực hiện thay đổi có thể gây lỗi ở Bazel để tuân thủ chính sách này.

Tuân thủ chính sách về tài liệu thiết kế.
Báo cáo vấn đề về GitHub.
Triển khai thay đổi.
Cập nhật nhãn.
Cập nhật kho lưu trữ.
Lật cờ không tương thích.

Vấn đề về GitHub

Báo cáo sự cố về GitHub trong kho lưu trữ Bazel. Xem ví dụ.

Bạn nên làm như sau:

Tiêu đề bắt đầu bằng tên của cờ (tên cờ sẽ bắt đầu bằng incompatible_).
Bạn thêm nhãn incompatible-change.
Phần mô tả chứa nội dung mô tả về thay đổi và đường liên kết đến các tài liệu thiết kế liên quan.
Phần mô tả chứa một công thức di chuyển để giải thích cho người dùng cách cập nhật mã. Lý tưởng nhất là khi thay đổi mang tính cơ học, hãy cung cấp đường liên kết đến công cụ di chuyển.
Nội dung mô tả này chứa một ví dụ về thông báo lỗi mà người dùng sẽ nhận được nếu họ không di chuyển. Điều này sẽ giúp các công cụ tìm kiếm dễ dàng phát hiện vấn đề trên GitHub hơn. Đảm bảo rằng thông báo lỗi hữu ích và dễ áp dụng. Khi có thể, thông báo lỗi phải bao gồm tên của cờ không tương thích.

Đối với công cụ di chuyển, hãy cân nhắc đóng góp cho Trình tạo. Dịch vụ này có thể áp dụng bản sửa lỗi tự động cho các tệp BUILD, WORKSPACE và .bzl. Ứng dụng cũng có thể báo cáo các cảnh báo.

Triển khai

Tạo cờ mới trong Bazel. Giá trị mặc định phải là false. Văn bản trợ giúp phải chứa URL của vấn đề về GitHub. Khi tên cờ bắt đầu bằng incompatible_, cần có thẻ siêu dữ liệu:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

Trong phần mô tả cam kết, thêm bản tóm tắt ngắn gọn về cờ. Ngoài ra, hãy thêm RELNOTES: vào biểu mẫu sau: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

Ngoài ra, bản cam kết cũng sẽ cập nhật tài liệu liên quan để không có cửa sổ cam kết, trong đó mã không nhất quán với tài liệu. Vì tài liệu của chúng tôi được tạo phiên bản, nên các thay đổi đối với tài liệu sẽ không vô tình bị huỷ bỏ sớm.

Nhãn

Sau khi hợp nhất cam kết và thay đổi không tương thích sẵn sàng để được áp dụng, hãy thêm nhãn migration-ready vào vấn đề GitHub.

Nếu phát hiện thấy vấn đề về cờ và người dùng có thể chưa di chuyển: hãy xóa cờ migration-ready.

Nếu bạn định lật cờ trong bản phát hành chính tiếp theo, hãy thêm nhãn `break-change-change-X.0" vào vấn đề.

Cập nhật kho lưu trữ

Bazel CI thử nghiệm danh sách các dự án quan trọng tại Bazel@HEAD + Downstream. Hầu hết các thành phần này thường là phần phụ thuộc của các dự án Bazel khác, vì vậy điều quan trọng là họ phải di chuyển các thành phần này để bỏ chặn việc di chuyển cho cộng đồng lớn. Để theo dõi trạng thái di chuyển của các dự án đó, bạn có thể sử dụng quy trình bazelisk-plus-incompatible-flags. Hãy tham khảo cách hoạt động của quy trình này tại đây.

Nhóm hỗ trợ nhà phát triển của chúng tôi sẽ giám sát nhãn migration-ready. Sau khi bạn thêm nhãn này vào vấn đề trên GitHub, họ sẽ xử lý những điều sau:

Tạo một nhận xét trong vấn đề GitHub để theo dõi danh sách các lỗi và dự án truyền xuống cần di chuyển (xem ví dụ)
Gửi vấn đề về tệp GitHub để thông báo cho chủ sở hữu về mọi dự án truyền xuống bị hỏng do sự thay đổi không tương thích (xem ví dụ)
Hãy theo dõi để đảm bảo bạn đã giải quyết tất cả các vấn đề trước ngày phát hành mục tiêu

Việc di chuyển các dự án trong quy trình xuôi dòng KHÔNG hoàn toàn thuộc trách nhiệm của tác giả thay đổi không tương thích, nhưng bạn có thể làm những việc sau để đẩy nhanh quá trình di chuyển và giúp cuộc sống của cả người dùng Bazel cũng như Nhóm Bazel Green trở nên dễ dàng hơn.

Gửi PR để khắc phục các dự án hạ nguồn.
Hãy liên hệ với cộng đồng Bazel để được trợ giúp di chuyển (ví dụ: Bazel Rules Authors SIG).

Lật cờ

Trước khi chuyển giá trị mặc định của cờ thành đúng, hãy đảm bảo:

Các kho lưu trữ cốt lõi trong hệ sinh thái sẽ được di chuyển.

Trên quy trình bazelisk-plus-incompatible-flags, cờ sẽ xuất hiện bên dưới The following flags didn't break any passing Bazel team owned/co-owned projects.
Tất cả các vấn đề trong danh sách kiểm tra được đánh dấu là đã khắc phục/đóng.
Mối quan tâm của người dùng và các câu hỏi đã được giải quyết.

Khi cờ đã sẵn sàng tung vào Bazel nhưng bị chặn khi di chuyển nội bộ tại Google, vui lòng đặt giá trị cờ thành false trong tệp blazerc nội bộ để bỏ chặn việc lật cờ. Bằng cách này, chúng tôi có thể đảm bảo người dùng Bazel dựa vào hành vi mới theo mặc định càng sớm càng tốt.

Khi thay đổi giá trị mặc định của cờ thành đúng, vui lòng:

Sử dụng RELNOTES[INC] trong phần mô tả cam kết, với định dạng sau: RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details Bạn có thể đưa thêm thông tin vào phần còn lại của phần mô tả cam kết.
Sử dụng Fixes #xyz trong phần mô tả để vấn đề về GitHub bị đóng khi hợp nhất cam kết.
Xem lại và cập nhật tài liệu nếu cần.
Gửi một vấn đề mới #abc để theo dõi việc xóa cờ.

Xóa cờ

Sau khi bị lật cờ ở HEAD, cuối cùng cần phải xoá cờ khỏi Bazel. Khi bạn định xóa cờ không tương thích:

Hãy cân nhắc để người dùng có thêm thời gian di chuyển nếu đó là một thay đổi lớn không tương thích. Cờ này nên có trong ít nhất một bản phát hành chính.
Đối với cam kết xoá cờ, hãy sử dụng Fixes #abc trong phần mô tả để vấn đề về GitHub bị đóng khi hợp nhất cam kết.