Kompatibilitas Aturan

Laporkan masalah Lihat sumber Per malam · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Aturan Bazel Starlark dapat melanggar kompatibilitas dengan rilis LTS Bazel di dua skenario berikut:

  1. Aturan ini melanggar kompatibilitas dengan rilis LTS mendatang karena fitur yang tergantung dihapus dari Bazel di HEAD.
  2. Aturan ini melanggar kompatibilitas dengan rilis LTS saat ini atau yang lebih lama karena fitur yang diperlukan hanya tersedia dalam rilis Bazel LTS yang lebih baru.

Sementara itu, aturan itu sendiri dapat mengirimkan perubahan yang tidak kompatibel untuk pengguna mereka sebagai ya. Jika dikombinasikan dengan perubahan yang dapat menyebabkan gangguan di Bazel, mengupgrade versi aturan dan versi Bazel sering kali menjadi sumber frustrasi bagi pengguna Bazel. Ini kami membahas bagaimana pembuat aturan harus menjaga kompatibilitas aturan dengan Bazel untuk memudahkan pengguna untuk meningkatkan versi Bazel dan aturan.

Proses migrasi yang dapat dikelola

Meskipun jelas tidak layak untuk menjamin kompatibilitas antara setiap versi Bazel dan setiap versi aturan tersebut, tujuan kami adalah memastikan bahwa proses migrasi tetap mudah dikelola bagi pengguna Bazel. Migrasi yang dapat dikelola didefinisikan sebagai proses di mana pengguna tidak dipaksa untuk meningkatkan versi utama aturan dan versi utama Bazel secara bersamaan, sehingga memungkinkan pengguna untuk menangani perubahan yang tidak kompatibel dari satu sumber pada satu waktu.

Misalnya, dengan matriks kompatibilitas berikut:

  • Bermigrasi dari rules_foo 1.x + Bazel 4.x ke rules_foo 2.x + Bazel 5.x tidak dianggap mudah dikelola, karena pengguna perlu memperbarui versi utama dari aturan_foo dan Bazel secara bersamaan.
  • Bermigrasi dari rules_foo 2.x + Bazel 5.x ke rules_foo 3.x + Bazel 6.x adalah dianggap mudah dikelola, karena pengguna dapat meningkatkan versi rules_foo dari 2.x ke 3.x tanpa mengubah versi Bazel utama, lalu tingkatkan versi Bazel dari 5.x ke 6,x.
aturan_foo 1.x aturan_foo 2.x aturan_foo 3.x KEPALA
Bazel 4.x
Bazel 5.x
Bazel 6.x
KEPALA

❌: Tidak ada versi versi aturan utama yang kompatibel dengan Bazel LTS data.

✅: Setidaknya satu versi aturan kompatibel dengan versi terbaru dari Rilis LTS Bazel.

Praktik terbaik

Sebagai penulis aturan Bazel, Anda dapat memastikan proses migrasi yang mudah dikelola bagi pengguna dengan mengikuti praktik terbaik berikut:

  1. Aturan harus mengikuti Semantik Pembuatan versi: versi minor dari file yang sama versi utama kompatibel dengan versi sebelumnya.
  2. Aturan di HEAD harus kompatibel dengan rilis Bazel LTS terbaru.
  3. Aturan di HEAD harus kompatibel dengan Bazel di HEAD. Untuk mencapai hal ini, Anda dapat
    • Siapkan pengujian CI Anda sendiri dengan Bazel di HEAD
    • Menambahkan project Anda ke Bazel downstream testing; masalah file tim Bazel ke proyek Anda jika ada perubahan yang dapat menyebabkan mempengaruhi proyek Anda, dan Anda harus mengikuti proyek downstream kami kebijakan untuk mengatasi masalah secara tepat waktu.
  4. Versi utama terbaru aturan harus kompatibel dengan versi terbaru Rilis LTS Bazel.
  5. Versi utama aturan yang baru harus kompatibel dengan Bazel LTS terakhir yang didukung oleh versi utama aturan sebelumnya.

Mencapai tugas 2. dan 3. adalah tugas yang paling penting karena memungkinkan untuk mencapai 4. dan 5. secara alami.

Untuk memudahkan Anda menjaga kompatibilitas dengan Bazel di HEAD dan versi terbaru Rilis Bazel LTS, pembuat aturan dapat:

  • Meminta fitur yang kompatibel dengan versi lama untuk di-backport ke LTS terbaru rilis, lihat proses rilis untuk mengetahui detail selengkapnya.
  • Menggunakan bazel_features untuk melakukan deteksi fitur Bazel.

Secara umum, dengan pendekatan yang direkomendasikan, aturan harus dapat bermigrasi untuk Bazel melakukan perubahan yang tidak kompatibel dan memanfaatkan fitur Bazel baru di HEAD tanpa menjatuhkan kompatibilitas dengan rilis Bazel LTS terbaru.