Kami tentu akan melakukan perubahan yang dapat menyebabkan gangguan pada Bazel. Kami harus mengubah desain dan memperbaiki hal-hal yang kurang berfungsi. Namun, kami perlu memastikan bahwa komunitas dan ekosistem Bazel dapat mengikuti. Oleh karena itu, project Bazel telah mengadopsi kebijakan kompatibilitas mundur. Dokumen ini menjelaskan proses bagi kontributor Bazel untuk membuat perubahan yang dapat menyebabkan gangguan pada Bazel guna 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 diawali 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 kodenya. Idealnya, jika perubahan bersifat mekanis, sertakan link ke alat migrasi.
Deskripsi ini mencakup contoh pesan error yang akan diterima pengguna jika mereka tidak melakukan migrasi. Tindakan ini akan membuat masalah GitHub lebih mudah ditemukan dari mesin telusur. Pastikan pesan error tersebut berguna dan dapat ditindaklanjuti. Jika memungkinkan, pesan error harus menyertakan nama flag yang tidak kompatibel.
Untuk alat migrasi, pertimbangkan untuk berkontribusi pada
Buildifier.
Ini dapat menerapkan perbaikan otomatis ke file BUILD
, WORKSPACE
, dan .bzl
.
Android Studio juga dapat melaporkan peringatan.
Implementasi
Buat bendera baru di Bazel. Nilai default harus salah. Teks bantuan
harus berisi URL masalah GitHub. Karena dimulai dengan incompatible_
, nama flag memerlukan tag metadata:
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
Dalam 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 agar tidak ada jendela commit yang kodenya tidak konsisten dengan dokumennya. Karena dokumentasi kami menggunakan versi, perubahan pada dokumen tidak akan dirilis secara tidak sengaja sebelum waktunya.
Label
Setelah commit digabungkan dan perubahan yang tidak kompatibel siap digunakan, tambahkan label
migration-ready
ke masalah GitHub.
Jika ditemukan masalah pada flag dan pengguna diperkirakan tidak akan melakukan migrasi:
hapus tanda migration-ready
.
Jika Anda berencana untuk membalik tanda di rilis utama berikutnya, tambahkan label `breaking-change-X.0" ke masalah.
Mengupdate repositori
Bazel CI menguji daftar project penting di Bazel@HEAD + Downstream. Sebagian besar dependensi tersebut sering kali merupakan
dependensi project Bazel lainnya, sehingga penting untuk memigrasikannya agar berhenti memblokir migrasi untuk komunitas yang lebih luas. Untuk memantau status migrasi project tersebut, Anda dapat menggunakan pipeline bazelisk-plus-incompatible-flags
.
Periksa cara kerja pipeline ini di sini.
Tim dukungan developer kami memantau label migration-ready
. Setelah Anda menambahkan label 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 yang tidak kompatibel (lihat contoh)
Tindak lanjuti untuk memastikan semua masalah telah 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 Tim Bazel Green.
Kirim PR untuk memperbaiki project downstream.
Hubungi komunitas Bazel untuk mendapatkan bantuan terkait migrasi (misalnya, Bazel Rules Authors SIG).
Membalik bendera
Sebelum membalik nilai default flag ke benar, pastikan bahwa:
Repositori inti dalam ekosistem akan dimigrasikan.
Di pipeline
bazelisk-plus-incompatible-flags
, flag akan muncul di bawahThe following flags didn't break any passing Bazel team owned/co-owned projects
.Semua masalah dalam checklist ditandai sebagai diperbaiki/ditutup.
Masalah dan pertanyaan pengguna telah diselesaikan.
Saat tanda siap siap di Bazel, tetapi diblokir saat migrasi internal di Google, pertimbangkan untuk menetapkan nilai tanda ke salah dalam file blazerc
internal untuk berhenti memblokir membalik tanda. Dengan melakukan ini, kita dapat memastikan pengguna Bazel bergantung pada perilaku baru secara default sedini mungkin.
Saat mengubah flag default ke true (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 dalam deskripsi commit lainnya. - Gunakan
Fixes #xyz
dalam deskripsi agar masalah GitHub ditutup saat commit digabungkan. - Tinjau dan perbarui dokumentasi jika diperlukan.
- Laporkan masalah baru
#abc
untuk melacak penghapusan tanda.
Menghapus tanda
Setelah bendera dibalik di HEAD, bendera pada akhirnya harus dihapus dari Bazel. Jika Anda berencana untuk menghapus flag yang tidak kompatibel:
- Pertimbangkan untuk memberikan lebih banyak waktu bagi pengguna untuk bermigrasi jika ini adalah perubahan besar yang tidak kompatibel. Idealnya, tanda harus tersedia di setidaknya satu rilis utama.
- Untuk commit yang menghapus flag, gunakan
Fixes #abc
dalam deskripsi agar masalah GitHub ditutup saat commit digabungkan.