Aturan Bazel Starlark dapat merusak kompatibilitas dengan rilis Bazel LTS 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 diandalkannya hanya tersedia dalam rilis Bazel LTS yang lebih baru.
Sementara itu, aturan itu sendiri dapat mengirimkan perubahan yang tidak kompatibel bagi penggunanya. Jika digabungkan dengan perubahan yang dapat menyebabkan gangguan di Bazel, mengupgrade versi aturan dan versi Bazel sering kali dapat menjadi sumber masalah bagi pengguna Bazel. Halaman ini membahas cara pembuat aturan harus mempertahankan kompatibilitas aturan dengan Bazel untuk memudahkan pengguna mengupgrade Bazel dan aturan.
Proses migrasi yang dapat dikelola
Meskipun jelas tidak mungkin untuk menjamin kompatibilitas antara setiap versi Bazel dan setiap versi aturan, kami ingin memastikan bahwa proses migrasi tetap dapat dikelola oleh pengguna Bazel. Proses migrasi yang mudah 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:
- Bermigrasi 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.
- Bermigrasi dari Rules_foo 2.x + Bazel 5.x ke Rules_foo 3.x + Bazel 6.x dianggap dapat dikelola, karena pengguna dapat mengupgrade aturan_foo terlebih dahulu dari 2.x ke 3.x 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 terbaru rilis Bazel LTS.
Praktik terbaik
Sebagai penulis aturan Bazel, Anda dapat memastikan proses migrasi yang mudah dikelola untuk pengguna dengan mengikuti praktik terbaik berikut:
- Aturan ini harus mengikuti Pembuatan Versi Semantik: versi minor dari versi utama yang sama kompatibel dengan versi sebelumnya.
- Aturan di HEAD harus kompatibel dengan rilis Bazel LTS terbaru.
- Aturan di HEAD harus kompatibel dengan Bazel di HEAD. Untuk melakukannya,
Anda dapat
- Siapkan pengujian CI Anda sendiri dengan Bazel di HEAD
- Tambahkan project Anda ke pengujian downstream Bazel; tim Bazel mengajukan 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 aturan terbaru harus kompatibel dengan rilis Bazel LTS terbaru.
- Versi utama aturan yang baru harus kompatibel dengan rilis Bazel LTS terakhir yang didukung oleh aturan versi utama sebelumnya.
Mencapai 2. dan 3. adalah tugas paling penting karena memungkinkan pencapaian 4. dan 5. tentu saja.
Untuk memudahkan menjaga kompatibilitas dengan Bazel di HEAD dan rilis Bazel LTS terbaru, pembuat aturan dapat:
- Minta fitur yang kompatibel dengan versi sebelumnya untuk di-backport ke rilis LTS terbaru, lihat proses rilis untuk detail selengkapnya.
- Gunakan bazel_features untuk melakukan deteksi fitur Bazel.
Secara umum, dengan pendekatan yang direkomendasikan, aturan harus dapat bermigrasi untuk perubahan Bazel yang tidak kompatibel dan dapat menggunakan fitur Bazel baru di HEAD tanpa menghentikan kompatibilitas dengan rilis Bazel LTS terbaru.