Khả năng tương thích quy tắc

Nightly · 9.2 · 9.1 · 9.0 · 8.7 · 8.6

Các quy tắc Bazel Starlark có thể phá vỡ khả năng tương thích với các bản phát hành Bazel LTS trong 2 trường hợp sau:

  1. Quy tắc này phá vỡ khả năng tương thích với các bản phát hành LTS trong tương lai vì một tính năng mà quy tắc này phụ thuộc đã bị xoá khỏi Bazel ở HEAD.
  2. Quy tắc này phá vỡ khả năng tương thích với các bản phát hành LTS hiện tại hoặc cũ hơn vì một tính năng mà quy tắc này phụ thuộc chỉ có trong các bản phát hành Bazel LTS mới hơn.

Trong khi đó, bản thân quy tắc này cũng có thể gửi các thay đổi không tương thích cho người dùng. Khi kết hợp với các thay đổi gây lỗi trong Bazel, việc nâng cấp phiên bản quy tắc và phiên bản Bazel thường có thể gây khó chịu cho người dùng Bazel. Trang này trình bày cách tác giả quy tắc nên duy trì khả năng tương thích của quy tắc với Bazel để giúp người dùng dễ dàng nâng cấp Bazel và các quy tắc hơn.

Quy trình di chuyển có thể quản lý

Mặc dù rõ ràng là không thể đảm bảo khả năng tương thích giữa mọi phiên bản Bazel và mọi phiên bản quy tắc, nhưng mục tiêu của chúng tôi là đảm bảo rằng quy trình di chuyển vẫn có thể quản lý được đối với người dùng Bazel. Quy trình di chuyển có thể quản lý được định nghĩa là một quy trình mà người dùng không buộc phải nâng cấp phiên bản chính của quy tắc và phiên bản chính của Bazel cùng một lúc, nhờ đó cho phép người dùng xử lý các thay đổi không tương thích từ một nguồn tại một thời điểm.

Ví dụ: với ma trận tương thích sau:

  • Việc di chuyển từ rules_foo 1.x + Bazel 4.x sang rules_foo 2.x + Bazel 5.x không được coi là có thể quản lý được, vì người dùng cần nâng cấp phiên bản chính của rules_foo và Bazel cùng một lúc.
  • Việc di chuyển từ rules_foo 2.x + Bazel 5.x sang rules_foo 3.x + Bazel 6.x được coi là có thể quản lý được, vì người dùng có thể nâng cấp rules_foo từ 2.x lên 3.x mà không cần thay đổi phiên bản chính của Bazel, sau đó nâng cấp Bazel từ 5.x lên 6.x.
rules_foo 1.x rules_foo 2.x rules_foo 3.x HEAD
Bazel 4.x ✅ ❌ ❌ ❌
Bazel 5.x ❌ ✅ ✅ ❌
Bazel 6.x ❌ ❌ ✅ ✅
HEAD ❌ ❌ ❌ ✅

❌: Không có phiên bản nào của phiên bản quy tắc chính tương thích với bản phát hành Bazel LTS.

✅: Ít nhất một phiên bản của quy tắc tương thích với phiên bản mới nhất của bản phát hành Bazel LTS.

Các phương pháp hay nhất

Là tác giả quy tắc Bazel, bạn có thể đảm bảo quy trình di chuyển có thể quản lý được cho người dùng bằng cách làm theo các phương pháp hay nhất sau đây:

  1. Quy tắc này phải tuân theo Quy trình tạo phiên bản ngữ nghĩa: các phiên bản phụ của cùng một phiên bản chính tương thích ngược.
  2. Quy tắc ở HEAD phải tương thích với bản phát hành Bazel LTS mới nhất.
  3. Quy tắc ở HEAD phải tương thích với Bazel ở HEAD. Để đạt được điều này, bạn có thể
  4. Phiên bản chính mới nhất của quy tắc phải tương thích với bản phát hành Bazel LTS mới nhất.
  5. Phiên bản chính mới của quy tắc phải tương thích với bản phát hành Bazel LTS cuối cùng được phiên bản chính trước đó của quy tắc hỗ trợ.

Việc đạt được 2. và 3. là nhiệm vụ quan trọng nhất vì điều này cho phép đạt được 4. và 5. một cách tự nhiên.

Để giúp dễ dàng duy trì khả năng tương thích với cả Bazel ở HEAD và bản phát hành Bazel LTS mới nhất, tác giả quy tắc có thể:

  • Yêu cầu chuyển các tính năng tương thích ngược sang bản phát hành LTS mới nhất, hãy xem quy trình phát hành để biết thêm thông tin.
  • Sử dụng bazel_features để thực hiện tính năng phát hiện Bazel.

Nói chung, với các phương pháp được đề xuất, các quy tắc sẽ có thể di chuyển cho các thay đổi không tương thích của Bazel và sử dụng các tính năng mới của Bazel ở HEAD mà không làm giảm khả năng tương thích với bản phát hành Bazel LTS mới nhất.