Aturan Bazel Starlark dapat melanggar kompatibilitas dengan rilis LTS Bazel dalam dua skenario berikut:
- Aturan ini melanggar kompatibilitas dengan rilis LTS mendatang karena fitur yang bergantung padanya akan dihapus dari Bazel di HEAD.
- Aturan ini melanggar kompatibilitas dengan rilis LTS saat ini atau yang lebih lama karena fitur yang menjadi dependensinya hanya tersedia dalam rilis LTS Bazel yang lebih baru.
Sementara itu, aturan itu sendiri juga dapat mengirimkan perubahan yang tidak kompatibel untuk penggunanya. Jika digabungkan dengan perubahan yang dapat menyebabkan gangguan pada Bazel, mengupgrade versi aturan dan versi Bazel sering kali dapat menjadi masalah bagi pengguna Bazel. Halaman ini membahas cara pembuat aturan menjaga kompatibilitas aturan dengan Bazel untuk memudahkan pengguna mengupgrade Bazel dan aturan.
Proses migrasi yang dapat dikelola
Meski jelas tidak memungkinkan untuk menjamin kompatibilitas antara setiap versi Bazel dan setiap versi aturan, tujuan kami adalah memastikan bahwa proses migrasi tetap dapat dikelola bagi pengguna Bazel. Proses migrasi yang dapat dikelola didefinisikan sebagai proses saat pengguna tidak dipaksa untuk mengupgrade aturan versi utama dan versi utama Bazel secara bersamaan, sehingga memungkinkan pengguna 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 harus mengupgrade versi utama rules_foo dan Bazel secara bersamaan.
- Bermigrasi dari rules_foo 2.x + Bazel 5.x ke rules_foo 3.x + Bazel 6.x dianggap mudah dikelola, karena pengguna dapat mengupgrade rules_foo dari 2.x ke 3.x terlebih dahulu tanpa mengubah versi utama Bazel, lalu mengupgrade Bazel dari 5.x ke 6.x.
| aturan_foo 1.x | aturan_foo 2.x | aturan_foo 3.x | HEAD | |
|---|---|---|---|---|
| Bazel 4.x | ✅ | ❌ | ❌ | ❌ |
| Bazel 5.x | ❌ | ✅ | ✅ | ❌ |
| Bazel 6.x | ❌ | ❌ | ✅ | ✅ |
| HEAD | ❌ | ❌ | ❌ | ✅ |
❌: Tidak ada versi versi aturan utama yang kompatibel dengan rilis Bazel LTS.
✅: Setidaknya satu versi aturan kompatibel dengan versi rilis LTS Bazel terbaru.
Praktik terbaik
Sebagai penulis aturan Bazel, Anda dapat memastikan proses migrasi yang mudah dikelola bagi pengguna dengan mengikuti praktik terbaik berikut:
- Aturan ini harus mengikuti Pembuatan Versi Semantik: versi minor dari versi utama yang sama kompatibel dengan versi lama.
- Aturan di HEAD harus kompatibel dengan rilis Bazel LTS terbaru.
- Aturan di HEAD harus kompatibel dengan Bazel di HEAD. Untuk mencapainya,
Anda dapat
- Siapkan pengujian CI Anda sendiri dengan Bazel di HEAD
- Tambahkan project Anda ke pengujian downstream Bazel; tim Bazel akan melaporkan masalah ke project Anda jika perubahan yang dapat menyebabkan gangguan pada Bazel memengaruhi project Anda, dan Anda harus mengikuti kebijakan project downstream kami untuk mengatasi masalah secara tepat waktu.
- Versi utama terbaru dari aturan tersebut harus kompatibel dengan rilis Bazel LTS terbaru.
- Versi utama baru dari aturan harus kompatibel dengan rilis Bazel LTS terakhir yang didukung oleh versi utama aturan sebelumnya.
Mencapai tugas 2. dan 3. adalah tugas terpenting karena memungkinkan pencapaian 4. dan 5. secara alami.
Untuk memudahkan mempertahankan kompatibilitas dengan Bazel di HEAD dan rilis Bazel LTS terbaru, pembuat aturan dapat:
- Meminta fitur yang kompatibel dengan versi lama untuk di-backport ke rilis LTS terbaru, lihat proses rilis untuk mengetahui detail selengkapnya.
- Gunakan bazel_features untuk melakukan deteksi fitur Bazel.
Secara umum, dengan pendekatan yang direkomendasikan, aturan harus dapat bermigrasi untuk perubahan yang tidak kompatibel dengan Bazel dan menggunakan fitur Bazel baru di HEAD tanpa menurunkan kompatibilitas dengan rilis Bazel LTS terbaru.