Chúng tôi chắc chắn sẽ thực hiện các thay đổi có thể gây lỗi cho Bazel. Chúng ta sẽ phải thay đổi thiết kế và khắc phục những điểm chưa ổn. Tuy nhiên, chúng ta cần đảm bảo rằng cộng đồng và hệ sinh thái Bazel có thể theo dõi. Để đạt được mục tiêu đó, dự án Bazel đã áp dụng một chính sách tương thích ngược. Tài liệu này mô tả quy trình để người đóng góp Bazel thực hiện một thay đổi mang tính đột phá trong Bazel nhằm tuân thủ chính sách này.
Tuân thủ chính sách về tài liệu thiết kế.
Vấn đề trên GitHub
Gửi vấn đề trên GitHub trong kho lưu trữ Bazel. Xem ví dụ.
Bạn nên:
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.Nội dung mô tả có nội dung mô tả về thay đổi và đường liên kết đến các tài liệu thiết kế có liên quan.
Nội dung mô tả có chứa một công thức di chuyển để giải thích cho người dùng cách họ nên cập nhật mã. Tốt nhất là khi có thay đổi về cơ chế, hãy thêm một đường liên kết đến công cụ di chuyển.
Nội dung mô tả có 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 vấn đề trên GitHub dễ được phát hiện hơn trên các công cụ tìm kiếm. Đảm bảo rằng thông báo lỗi hữu ích và có thể xử lý. Nếu có thể, thông báo lỗi phải có 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 việc đóng góp cho Buildifier.
Công cụ này có thể áp dụng các bản sửa lỗi tự động cho tệp BUILD, WORKSPACE và .bzl.
Công cụ này cũng có thể báo cáo các cảnh báo.
Triển khai
Tạo một 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 đề trên GitHub. Vì tên cờ bắt đầu bằng incompatible_, nên cần có thẻ siêu dữ liệu:
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
Trong phần mô tả cam kết, hãy thêm nội dung tóm tắt ngắn gọn về cờ.
Bạn cũng có thể thêm RELNOTES: theo biểu mẫu sau:
RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
Cam kết cũng phải cập nhật tài liệu liên quan để không có khoảng thời gian cam kết nào mà 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 phân phiên bản, nên những thay đổi đối với tài liệu sẽ không vô tình được phát hành quá sớm.
Nhãn
Sau khi cam kết được hợp nhấ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 đề trên GitHub.
Nếu cờ có vấn đề và người dùng chưa cần di chuyển: xoá cờ migration-ready.
Nếu bạn dự định chuyển đổi cờ trong bản phát hành chính tiếp theo, hãy thêm nhãn "breaking-change-X.0" vào vấn đề.
Cập nhật kho lưu trữ
Bazel CI kiểm thử danh sách các dự án quan trọng tại Bazel@HEAD + Downstream. Hầu hết các dự án này thường là các phần phụ thuộc của các dự án Bazel khác, do đó, việc di chuyển các dự án này là rất quan trọng để mở đường cho việc di chuyển đối với cộng đồng rộng lớn hơn. Để theo dõi trạng thái di chuyển của những dự án đó, bạn có thể sử dụng quy trình bazelisk-plus-incompatible-flags.
Xem 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 theo dõi 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 việc sau:
Tạo một bình luận trong vấn đề trên GitHub để theo dõi danh sách các lỗi và dự án hạ nguồn cần được di chuyển (xem ví dụ)
Gửi vấn đề trên GitHub để thông báo cho chủ sở hữu của mọi dự án hạ nguồn bị ảnh hưởng bởi thay đổi không tương thích của bạn (xem ví dụ)
Theo dõi để đảm bảo tất cả vấn đề đều được giải quyết 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 hạ nguồn KHÔNG hoàn toàn là 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ư sau để đẩy nhanh quá trình di chuyển và giúp cả người dùng Bazel cũng như Nhóm Bazel Green dễ dàng hơn.
Gửi yêu cầu kéo để sửa các dự án hạ nguồn.
Liên hệ với cộng đồng Bazel để được trợ giúp về việc di chuyển (ví dụ: SIG của tác giả quy tắc Bazel).
Lật cờ
Trước khi chuyển giá trị mặc định của cờ thành true, vui lòng đảm bảo rằng:
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 trongThe following flags didn't break any passing Bazel team owned/co-owned projects.Tất cả vấn đề trong danh sách kiểm tra đều được đánh dấu là đã khắc phục/đã đóng.
Các thắc mắc và câu hỏi của người dùng đã được giải quyết.
Khi cờ đã sẵn sàng chuyển đổi trong Bazel nhưng bị chặn trong quá trình di chuyển nội bộ tại Google, vui lòng cân nhắc đặt giá trị cờ thành false trong tệp blazerc nội bộ để bỏ chặn quá trình chuyển đổi cờ. Bằng cách này, chúng tôi có thể đảm bảo người dùng Bazel mặc định phụ thuộc vào hành vi mới càng sớm càng tốt.
Khi thay đổi cờ mặc định thành true, vui lòng:
- Sử dụng
RELNOTES[INC]trong nội dung mô tả cam kết, theo định dạng sau:RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for detailsBạn có thể thêm thông tin khác vào phần còn lại của nội dung mô tả cam kết. - Sử dụng
Fixes #xyztrong nội dung mô tả để vấn đề trên GitHub được đóng khi cam kết được hợp nhất. - Xem xét 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 xoá cờ.
Xoá cờ
Sau khi cờ được chuyển đổi tại HEAD, cuối cùng cờ này sẽ bị xoá khỏi Bazel. Khi bạn dự định xoá cờ không tương thích:
- Hãy cân nhắc dành thêm thời gian để người dùng di chuyển nếu đó là một thay đổi lớn không tương thích. Tốt nhất là cờ này phải 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 #abctrong phần mô tả để vấn đề trên GitHub được đóng khi cam kết được hợp nhất.