Chúng tôi chắc chắn sẽ thực hiện các thay đổi mang tính đột phá đối với Bazel. Chúng tôi sẽ phải thay đổi thiết kế và khắc phục những điểm chưa hoạt động hiệu quả. Tuy nhiên, chúng tôi cần đảm bảo rằng cộng đồng và hệ sinh thái Bazel có thể làm theo. Để đạt được mục tiêu đó, dự án Bazel đã áp dụng chính sách tương thích ngược. Tài liệu này mô tả quy trình để những người đóng góp cho Bazel thực hiện 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ả 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ế có liên quan.
Nội dung mô tả chứa 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 thay đổi mang tính cơ học, hãy thêm đường liên kết đến a công cụ di chuyển.
Nội dung mô tả bao gồm ví dụ về thông báo lỗi mà người dùng sẽ nhận được nếu 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 từ. Đảm bảo rằng thông báo lỗi hữu ích và có thể thực hiện. Khi có thể, thông báo lỗi nên 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
Buildifier.
Công cụ này có thể áp dụng các bản sửa lỗi tự động cho các tệp BUILD, WORKSPACE và .bzl.
Công cụ này cũng có thể báo cáo 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 đề trên GitHub. Vì tên cờ bắt đầu bằng
incompatible_, nên cần có các thẻ siêu dữ liệu:
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
Trong nội dung mô tả cam kết, hãy thêm bản tóm tắt ngắn gọn về cờ.
Đồng thời, hãy thêm RELNOTES: theo mẫu sau:
RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
Cam kết cũng nên cập nhật tài liệu có liên quan để không có cửa sổ 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 kiểm soát phiên bản, nên các thay đổi đối với tài liệu sẽ không vô tình được phát hành 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 phát hiện thấy vấn đề với cờ và người dùng chưa di chuyển:
hãy xoá cờ migration-ready.
Nếu bạn dự định đảo ngược 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à phần phụ thuộc của các dự án Bazel khác, vì vậy, việc di chuyển các dự án này là rất quan trọng để mở khoá quá trình di chuyển cho cộng đồng rộng lớn hơ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 pipeline,
hãy xem cách hoạt động của quy trình này tại đây.
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. Tuy nhiên, bạn có thể thực hiện những việc sau để đẩy nhanh quá trình di chuyển và giúp người dùng Bazel cũng như Nhóm Bazel Green dễ dàng hơn.
- Gửi vấn đề trên GitHub để thông báo cho chủ sở hữu của các dự án hạ nguồn bị thay đổi không tương thích của bạn làm hỏng.
- Gửi yêu cầu kéo để khắc phục các dự án hạ nguồn.
- Liên hệ với cộng đồng Bazel để được trợ giúp về quá trình di chuyển (ví dụ: Nhóm lợi ích đặc biệt của tác giả quy tắc Bazel).
Đảo ngược cờ
Trước khi đảo ngược 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 được di chuyển.
Trên quy trình
bazelisk-plus-incompatible-flagspipeline, cờ sẽ xuất hiện trong phầnThe following flags didn't break any passing Bazel team owned/co-owned projects.Các mối lo ngại và câu hỏi của người dùng đã được giải quyết.
Khi cờ đã sẵn sàng đảo ngược 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 nội bộ blazerc để mở chặn quá trình đảo ngược cờ. Bằng cách này, chúng ta có thể đảm bảo người dùng Bazel phụ thuộc 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 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 bổ sung 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 đóng lại 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 vấn đề mới
#abcđể theo dõi việc xoá cờ.
Xoá cờ
Sau khi cờ được đảo ngược tại HEAD, cờ đó sẽ bị xoá khỏi Bazel. Khi bạn dự định xoá cờ không tương thích:
- Cân nhắc dành thêm thời gian cho người dùng di chuyển nếu đó là thay đổi không tương thích lớn. Tốt nhất là cờ phải có sẵn 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 nội dung mô tả để vấn đề trên GitHub đóng lại khi cam kết được hợp nhất.