Kami tidak dapat menghindari perubahan yang menyebabkan error pada Bazel. Kita harus mengubah desain dan memperbaiki hal-hal yang tidak berfungsi dengan baik. Namun, kita perlu memastikan bahwa komunitas dan ekosistem Bazel dapat mengikutinya. Untuk itu, project Bazel telah mengadopsi kebijakan kompatibilitas mundur. Dokumen ini menjelaskan proses bagi kontributor Bazel dalam melakukan perubahan yang dapat menyebabkan gangguan di Bazel agar mematuhi kebijakan ini.
Ikuti kebijakan dokumen desain.
Masalah GitHub
Laporkan masalah GitHub di repositori Bazel. Lihat contoh.
Sebaiknya:
Judul dimulai dengan nama flag (nama flag akan dimulai dengan
incompatible_
).Anda dapat menambahkan label
incompatible-change
.Deskripsi berisi deskripsi perubahan dan link ke dokumen desain yang relevan.
Deskripsi berisi resep migrasi, untuk menjelaskan kepada pengguna cara memperbarui kode mereka. Idealnya, jika perubahan bersifat mekanis, sertakan link ke alat migrasi.
Deskripsi menyertakan contoh pesan error yang akan diterima pengguna jika mereka tidak bermigrasi. Tindakan ini akan membuat masalah GitHub lebih mudah ditemukan dari mesin telusur. Pastikan pesan error bermanfaat dan dapat ditindaklanjuti. Jika memungkinkan, pesan error harus menyertakan nama flag yang tidak kompatibel.
Untuk alat migrasi, pertimbangkan untuk berkontribusi pada
Buildifier.
Aplikasi ini dapat menerapkan perbaikan otomatis ke file BUILD
, WORKSPACE
, dan .bzl
.
Alat ini juga dapat melaporkan peringatan.
Penerapan
Buat flag baru di Bazel. Nilai defaultnya harus salah. Teks bantuan
harus berisi URL masalah GitHub. Karena nama flag dimulai dengan
incompatible_
, flag memerlukan tag metadata:
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
Di deskripsi commit, tambahkan ringkasan singkat flag.
Tambahkan juga RELNOTES:
dalam bentuk berikut:
RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
Commit juga harus memperbarui dokumentasi yang relevan, sehingga tidak ada periode commit saat kode tidak konsisten dengan dokumen. Karena dokumentasi kami memiliki versi, perubahan pada dokumen tidak akan dirilis secara tidak sengaja sebelum waktunya.
Label
Setelah commit digabungkan dan perubahan yang tidak kompatibel siap diterapkan, tambahkan label
migration-ready
ke masalah GitHub.
Jika masalah ditemukan pada tanda dan pengguna belum diharapkan untuk bermigrasi:
hapus tanda migration-ready
.
Jika Anda berencana untuk mengaktifkan tanda tersebut di rilis utama berikutnya, tambahkan label `breaking-change-X.0" ke masalah tersebut.
Memperbarui repositori
Bazel CI menguji daftar project penting di
Bazel@HEAD + Downstream. Sebagian besar project tersebut sering kali merupakan
dependensi project Bazel lainnya, sehingga penting untuk memigrasikannya agar dapat berhenti memblokir migrasi untuk komunitas yang lebih luas. Untuk memantau status migrasi project tersebut, Anda dapat menggunakan pipeline bazelisk-plus-incompatible-flags
.
Lihat cara kerja pipeline ini di sini.
Tim dukungan developer kami memantau label migration-ready
. Setelah Anda menambahkan label ini ke masalah GitHub, label tersebut akan menangani hal berikut:
Buat komentar di masalah GitHub untuk melacak daftar kegagalan dan project downstream yang perlu dimigrasikan (lihat contoh)
Laporkan masalah Github untuk memberi tahu pemilik setiap project downstream yang rusak karena perubahan Anda yang tidak kompatibel (lihat contoh)
Lakukan tindak lanjut untuk memastikan semua masalah ditangani sebelum tanggal rilis target
Memigrasikan project di pipeline downstream TIDAK sepenuhnya menjadi tanggung jawab penulis perubahan yang tidak kompatibel, tetapi Anda dapat melakukan hal berikut untuk mempercepat migrasi dan memudahkan pengguna Bazel dan Bazel Green Team.
Mengirim PR untuk memperbaiki project downstream.
Hubungi komunitas Bazel untuk mendapatkan bantuan terkait migrasi (misalnya, Bazel Rules Authors SIG).
Mengibarkan bendera
Sebelum mengubah nilai default tanda menjadi benar, pastikan:
Repositori inti di ekosistem dimigrasikan.
Di pipeline
bazelisk-plus-incompatible-flags
, tanda akan muncul di bagianThe following flags didn't break any passing Bazel team owned/co-owned projects
.Semua masalah dalam checklist ditandai sebagai telah diperbaiki/ditutup.
Masalah dan pertanyaan pengguna telah diselesaikan.
Jika flag siap dibalik di Bazel, tetapi diblokir pada migrasi internal di Google, sebaiknya tetapkan nilai flag ke salah (false) di file blazerc
internal untuk membatalkan pemblokiran flag flip. Dengan melakukan hal ini, kita dapat memastikan pengguna Bazel bergantung pada perilaku baru secara default sedini mungkin.
Saat mengubah flag default menjadi benar, harap:
- Gunakan
RELNOTES[INC]
dalam deskripsi commit, dengan format berikut:RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details
Anda dapat menyertakan informasi tambahan di bagian deskripsi commit lainnya. - Gunakan
Fixes #xyz
dalam deskripsi, sehingga masalah GitHub ditutup saat commit digabungkan. - Tinjau dan perbarui dokumentasi jika diperlukan.
- Ajukan masalah baru
#abc
untuk melacak penghapusan tanda.
Menghapus tanda
Setelah dibalik ke HEAD, bendera pada akhirnya harus dilepas dari Bazel. Jika Anda berencana menghapus flag yang tidak kompatibel:
- Pertimbangkan untuk memberikan lebih banyak waktu bagi pengguna untuk melakukan migrasi jika perubahan tersebut tidak kompatibel. Idealnya, flag harus tersedia setidaknya di satu rilis utama.
- Untuk commit yang menghapus flag, gunakan
Fixes #abc
dalam deskripsi sehingga masalah GitHub ditutup saat commit digabungkan.