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

Việc chúng tôi thực hiện những 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ế và sửa những thứ không 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ể đồng hành. Để đạ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 các cộng tác viên của Bazel thực hiện một thay đổi có thể gây lỗi ở Bazel để 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. Báo cáo vấn đề trên GitHub.

  3. Triển khai thay đổi.

  4. Cập nhật nhãn

  5. Lật 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.

  • Nội dung mô tả có chứa nội dung mô tả về thay đổi và một đường liên kết đến 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 cập nhật mã. Tốt nhất là khi thay đổi chỉ có tính cơ học, hãy thê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 họ không di chuyển. Cách này sẽ giúp các công cụ tìm kiếm dễ 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à hữu ích. 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 việc đóng góp cho Trình tạo bản dựng. Ứng dụng này có thể áp dụng các bản sửa lỗi tự động cho tệp BUILD, WORKSPACE và .bzl. Thiết bị 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ày 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 một 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

Cam kết cũng phải cập nhật tài liệu liên quan để không có thời lượng thay đổi nào 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 được phát hành 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 đề trên GitHub.

Nếu phát hiện thấy vấn đề với cờ và người dùng dự kiến chưa di chuyển, hãy xoá các 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 label " breaking-change-X.0 " vào vấn đề đó.

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 trong số đó thường là phần phụ thuộc của các dự án Bazel khác. Vì vậy, bạn cần phải di chuyển các dự án này để bỏ chặn 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, kiểm tra 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 phải hoàn toàn là trách nhiệm của tác giả của thay đổi không tương thích. Tuy nhiên, bạn có thể làm như sau để đẩy nhanh quá trình di chuyển và giúp cuộc sống của cả người dùng Bazel và Nhóm Bazel Green trở nên dễ dàng hơn.

  1. Gửi vấn đề trên GitHub để thông báo cho chủ sở hữu của các dự án tiếp theo bị hỏng do thay đổi không tương thích.
  2. Gửi PR để khắc phục các dự án tiếp theo.
  3. Liên hệ với cộng đồng Bazel để được trợ giúp về quá trình 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 true, hãy đả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 trong The following flags didn't break any passing Bazel team owned/co-owned projects.

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

Khi cờ đã sẵn sàng lật trong Bazel, nhưng bị chặn khi di chuyển nội bộ tại Google, vui lòng xem xét việc đặ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 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 cờ mặc định thành true, vui lòng:

  • Sử dụng RELNOTES[INC] trong phần mô tả dự trữ, 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 nội dung mô tả cam kết.
  • Sử dụng Fixes #xyz trong phần mô tả để vấn đề GitHub được đó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 xoá cờ.

Gỡ bỏ cờ

Sau khi được lật ở HEAD, cờ này sẽ được gỡ bỏ khỏi Bazel. Khi bạn định xoá cờ không tương thích:

  • Hãy cân nhắc việc dành thêm thời gian để người dùng di chuyển nếu đó là thay đổi lớn không tương thích. Lý tưởng nhất là cờ này xuất hiện trong ít nhất một bản phát hành chính.
  • Đối với lệnh xác nhận xoá cờ, hãy dùng Fixes #abc trong phần mô tả để vấn đề GitHub bị đóng khi hợp nhất lệnh xác nhận đó.