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

Báo cáo vấn đề Xem nguồn Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Chúng ta sẽ không thể tránh khỏi một số thay đổi có thể gây lỗi đối với Bazel. Chúng ta sẽ phải thay đổi thiết kế và khắc phục những vấn đề không hoạt động. 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. Do đó, 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 một thay đổi có thể gây lỗi trong Bazel nhằm tuân thủ chính sách này.

  1. Tuân thủ chính sách về tài liệu thiết kế.

  2. Gửi vấn đề trên GitHub.

  3. Triển khai thay đổi.

  4. Cập nhật nhãn.

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

  6. Đảo ngược cờ không tương thích.

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 tài liệu thiết kế 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 cập nhật mã. Tốt nhất là khi thay đổi là cơ học, hãy thêm đường liên kết đến 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 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ể hành động. Nếu 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 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. Trình phát hiện cũng có thể báo cáo 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ó các thẻ siêu dữ liệu:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

Trong phần mô tả thay đổi, hãy thêm nội dung tóm tắt ngắn gọn về cờ. Ngoài ra, hãy thêm RELNOTES: ở dạng 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ó giai đoạn cam kết 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 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 thay đổi không tương thích được chấp nhận và thay đổi đã cam kết được hợp nhất, hãy thêm nhãn migration-ready vào vấn đề trên GitHub.

Nếu bạn phát hiện 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 lật 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 đề.

Đang 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 đó, điều quan trọng là phải di chuyển các dự án này để bỏ chặn việc 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. Hãy 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:

  1. Tạo một nhận xét trong vấn đề trên GitHub để theo dõi danh sách các lỗi và dự án phụ cần di chuyển (xem ví dụ)

  2. 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ị lỗi do thay đổi không tương thích của bạn (xem ví dụ)

  3. Tiếp tục liên hệ để đảm bảo bạn đã giải quyết mọi vấn đề trước ngày phát hành dự kiến

Việc di chuyển các dự án trong quy trình phía hạ nguồn 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ư sau để đẩy nhanh quá trình di chuyển và giúp cả người dùng Bazel và Nhóm Bazel Green dễ dàng hơn.

  1. Gửi yêu cầu phát hành để khắc phục các dự án phụ thuộc.

  2. Hãy liên hệ với cộng đồng Bazel để được trợ giúp về việc di chuyển (ví dụ: SIG 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 được di chuyển.

    Trên quy trình bazelisk-plus-incompatible-flags, cờ sẽ xuất hiện trong The 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 này đều được đánh dấu là đã khắc phục/đã đóng.

  • 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 bật/tắt trong Bazel nhưng bị chặn khi 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 việc bật/tắt cờ. Bằng cách này, chúng tôi có thể đảm bảo người dùng Bazel phụ thuộc vào hành vi mới theo mặc định sớm nhất có thể.

Khi thay đổi cờ mặc định thành true, vui lòng:

  • Sử dụng RELNOTES[INC] trong phần mô tả cam kết theo đị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 nội dung mô tả để đóng vấn đề trên GitHub khi bạn hợp nhất thay đổi.
  • 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 gỡ bỏ cờ.

Xoá cờ

Sau khi cờ được lật tại HEAD, cờ này 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 để 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ờ này nên có trong ít nhất một bản phát hành chính.
  • Đối với thay đổi xoá cờ, hãy sử dụng Fixes #abc trong phần mô tả để đóng vấn đề trên GitHub khi thay đổi được hợp nhất.