Aturan Bazel Starlark dapat merusak kompatibilitas dengan rilis LTS Bazel dalam dua skenario berikut:
- Aturan ini merusak kompatibilitas dengan rilis LTS mendatang karena fitur yang diandalkannya dihapus dari Bazel di HEAD.
- Aturan ini merusak kompatibilitas dengan rilis LTS saat ini atau yang lebih lama karena fitur yang bergantung padanya hanya tersedia di rilis LTS Bazel yang lebih baru.
Sementara itu, aturan itu sendiri dapat mengirimkan perubahan yang tidak kompatibel untuk penggunanya. Jika digabungkan dengan perubahan yang menyebabkan gangguan pada Bazel, mengupgrade versi aturan dan versi Bazel sering kali menjadi sumber frustrasi bagi pengguna Bazel. Halaman ini membahas cara penulis aturan harus mempertahankan kompatibilitas aturan dengan Bazel untuk memudahkan pengguna mengupgrade Bazel dan aturan.
Proses migrasi yang mudah dikelola
Meskipun jelas tidak mungkin menjamin kompatibilitas antara setiap versi Bazel dan setiap versi aturan, tujuan kami adalah memastikan bahwa proses migrasi tetap dapat dikelola oleh pengguna Bazel. Proses migrasi yang dapat dikelola didefinisikan sebagai proses saat pengguna tidak dipaksa untuk mengupgrade versi utama aturan dan versi utama Bazel secara bersamaan, sehingga memungkinkan pengguna menangani perubahan yang tidak kompatibel dari satu sumber dalam satu waktu.
Misalnya, dengan matriks kompatibilitas berikut:
- Migrasi dari rules_foo 1.x + Bazel 4.x ke rules_foo 2.x + Bazel 5.x tidak dianggap dapat dikelola, karena pengguna harus mengupgrade versi utama rules_foo dan Bazel secara bersamaan.
- Migrasi dari rules_foo 2.x + Bazel 5.x ke rules_foo 3.x + Bazel 6.x dianggap dapat 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.
| rules_foo 1.x | rules_foo 2.x | rules_foo 3.x | KEPALA | |
|---|---|---|---|---|
| Bazel 4.x | ✅ | ❌ | ❌ | ❌ |
| Bazel 5.x | ❌ | ✅ | ✅ | ❌ |
| Bazel 6.x | ❌ | ❌ | ✅ | ✅ |
| KEPALA | ❌ | ❌ | ❌ | ✅ |
❌: Tidak ada versi aturan utama yang kompatibel dengan rilis Bazel LTS.
✅: Setidaknya satu versi aturan kompatibel dengan rilis LTS Bazel versi terbaru.
Praktik terbaik
Sebagai penulis aturan Bazel, Anda dapat memastikan proses migrasi yang mudah dikelola bagi pengguna dengan mengikuti praktik terbaik berikut:
- Aturan harus mengikuti Pembuatan Versi Semantik: versi minor dari versi mayor yang sama kompatibel mundur.
- Aturan di HEAD harus kompatibel dengan rilis LTS Bazel terbaru.
- Aturan di HEAD harus kompatibel dengan Bazel di HEAD. Untuk mencapainya,
Anda dapat
- Menyiapkan pengujian CI Anda sendiri dengan Bazel di HEAD
- Tambahkan project Anda ke pengujian downstream Bazel; tim Bazel akan mencatat masalah ke project Anda jika perubahan yang merusak di Bazel memengaruhi project Anda, dan Anda harus mengikuti kebijakan project downstream kami untuk mengatasi masalah secara tepat waktu.
- Versi utama terbaru aturan harus kompatibel dengan rilis LTS Bazel terbaru.
- Versi utama baru aturan harus kompatibel dengan rilis LTS Bazel terakhir yang didukung oleh versi utama aturan sebelumnya.
Mencapai 2. dan 3. adalah tugas yang paling penting karena memungkinkan tercapainya 4. dan 5. secara alami.
Untuk mempermudah mempertahankan kompatibilitas dengan Bazel di HEAD dan rilis LTS Bazel terbaru, penulis aturan dapat:
- Untuk meminta fitur yang kompatibel dengan versi sebelumnya di-back-port 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 dimigrasikan untuk perubahan yang tidak kompatibel dengan Bazel dan memanfaatkan fitur Bazel baru di HEAD tanpa menghilangkan kompatibilitas dengan rilis LTS Bazel terbaru.