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/3}

Chúng tôi sẽ thực hiện một số thay đổi có thể gây lỗi đối với Bazel là không thể tránh khỏi. Chúng tôi sẽ phải thay đổi thiết kế của mình và khắc phục những lỗi chưa hoạt động hiệu quả. Tuy nhiên, chúng tôi cần đảm bảo cộng đồng và hệ sinh thái Bazel có thể tuân thủ. Để đạ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 giúp 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 để tuân thủ chính sách này.

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

  2. Báo cáo vấn đề trên GitHub.

  3. Triển khai thay đổi này.

  4. Cập nhật nhãn

  5. Chuyển cờ không tương thích.

Vấn đề trên GitHub

Báo cáo vấn đề về GitHub trong kho lưu trữ Bazel. Xem ví dụ.

Bạn nên:

  • Tiêu đề bắt đầu bằng tên 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à một đường liên kết đến các tài liệu thiết kế có liên quan.

  • Phần 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 là cơ học, hãy bao gồm một đường liên kết đến công cụ di chuyển.

  • Nội dung mô tả có một 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ễ tìm thấy vấn đề GitHub hơn. Đảm bảo rằng thông báo lỗi là hữu ích và có thể xử lý được. 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 Buildifier. Công cụ này có thể áp dụng bản sửa lỗi tự động cho các tệp BUILD, WORKSPACE và .bzl. Ngoài ra, tính năng này 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ả cam kết, 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: vào 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ó 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 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 được phát hành sớm.

Nhãn

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

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

Nếu bạn dự định thay đổi nội dung 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ử một 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. Do đó, bạn cần di chuyển các dự án đó để bỏ chặn quá trình di chuyển cho cộng đồng nói chung.

Để 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, xem cách hoạt động của quy trình này tại đây.

Việc di chuyển dự án trong quy trình 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. Tuy nhiên, bạn có thể làm những việc sau để đẩy nhanh quá trình di chuyển và tạo điều kiện thuận lợi hơn cho cả người dùng Bazel và Nhóm Bazel Green.

  1. 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ị hỏng do thay đổi không tương thích của bạn.
  2. Gửi PR để khắc phục các dự án hạ nguồn.
  3. Liên hệ với cộng đồng Bazel để được trợ giúp về việc di chuyển (ví dụ: Bazel Rules Authors SIG).

Tung 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ữ chính 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.

  • Chúng tôi đã giải quyết các thắc mắc và mối lo ngại của người dùng.

Khi cờ đã sẵn sàng tung ra 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 việc tung cờ. Bằng cách này, chúng tôi có thể đảm bảo rằng 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 giá trị mặc định của cờ 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 phần mô tả để đóng vấn đề GitHub khi xác nhận (commit) được hợp nhất.
  • Xem lại và cập nhật tài liệu nếu cần.
  • Hãy báo cáo một vấn đề mới #abc để theo dõi việc xoá cờ.

Xoá cờ

Sau khi cờ được lật ở HEAD, cuối cùng bạn phải xoá cờ này khỏi Bazel. Khi bạn định xoá 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à sự 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 cam kết xoá cờ, hãy dùng Fixes #abc trong phần mô tả để đóng vấn đề GitHub khi xác nhận được hợp nhất.