Panduan untuk meluncurkan perubahan yang dapat menyebabkan gangguan

Tidak dapat dihindari bahwa kami akan membuat perubahan yang dapat menyebabkan gangguan pada Bazel. Kami harus mengubah desain dan memperbaiki hal-hal yang tidak berfungsi dengan baik. Namun, kami harus memastikan bahwa komunitas dan ekosistem Bazel dapat mengikutinya. Untuk itu, project Bazel telah mengadopsi kebijakan kompatibilitas mundur. Dokumen ini menjelaskan proses bagi kontributor Bazel untuk membuat perubahan yang dapat menyebabkan gangguan pada Bazel agar mematuhi kebijakan ini.

1. Ikuti kebijakan dokumen desain.

2. Laporkan masalah GitHub.

3. Terapkan perubahan.

4. Perbarui label.

5. Perbarui repositori.

6. Ubah flag yang tidak kompatibel.

Masalah GitHub

Laporkan masalah GitHub di repositori Bazel. Lihat contoh.

Sebaiknya:

• Judul dimulai dengan nama flag (nama flag akan dimulai dengan incompatible_).

• Anda 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 melakukan migrasi. Hal 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, sebaiknya berkontribusilah ke Buildifier. Alat ini dapat menerapkan perbaikan otomatis ke file BUILD, WORKSPACE, dan .bzl. Alat ini juga dapat melaporkan peringatan.

Penerapan

Buat flag baru di Bazel. Nilai default harus salah (false). Teks bantuan harus berisi URL masalah GitHub. Karena nama flag 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, sehingga tidak ada periode commit yang kodenya 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 diadopsi, tambahkan label migration-ready ke masalah GitHub.

Jika masalah ditemukan pada flag dan pengguna belum diharapkan untuk melakukan migrasi: hapus flag migration-ready.

Jika Anda berencana mengubah flag pada 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 guna membuka blokir 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, mereka akan menangani hal berikut:

1. Membuat komentar di masalah GitHub untuk melacak daftar kegagalan dan project downstream yang perlu dimigrasikan (lihat contoh)

2. Melaporkan masalah GitHub untuk memberi tahu pemilik setiap project downstream yang rusak akibat perubahan yang tidak kompatibel (lihat contoh)

3. Melakukan tindak lanjut untuk memastikan semua masalah ditangani sebelum tanggal rilis target

Memigrasikan project dalam pipeline downstream BUKAN sepenuhnya tanggung jawab penulis perubahan yang tidak kompatibel, tetapi Anda dapat melakukan hal berikut untuk mempercepat migrasi dan mempermudah pengguna Bazel dan Tim Hijau Bazel.

1. Mengirim PR untuk memperbaiki project downstream.

2. Menghubungi komunitas Bazel untuk mendapatkan bantuan terkait migrasi (misalnya, Bazel Rules Authors SIG).

Mengubah flag

Sebelum mengubah nilai default flag menjadi benar (true), pastikan bahwa:

• Repositori inti dalam ekosistem dimigrasikan.

  Di pipeline bazelisk-plus-incompatible-flags, flag akan muncul di bagian The following flags didn't break any passing Bazel team owned/co-owned projects.

• Semua masalah dalam checklist ditandai sebagai diperbaiki/ditutup.

• Kekhawatiran dan pertanyaan pengguna telah diselesaikan.

Jika flag siap diubah di Bazel, tetapi diblokir pada migrasi internal di Google, sebaiknya tetapkan nilai flag ke salah (false) dalam file blazerc internal untuk membuka blokir perubahan flag. Dengan melakukan hal ini, kita dapat memastikan pengguna Bazel bergantung pada perilaku baru secara default sesegera mungkin.

Saat mengubah default flag menjadi benar (true), lakukan hal berikut:

• 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 akan ditutup saat commit digabungkan.
• Tinjau dan perbarui dokumentasi jika diperlukan.
• Laporkan masalah baru #abc untuk melacak penghapusan flag.

Menghapus flag

Setelah flag diubah di HEAD, flag tersebut harus dihapus dari Bazel pada akhirnya. Saat Anda berencana menghapus flag yang tidak kompatibel:

• Sebaiknya berikan lebih banyak waktu kepada pengguna untuk melakukan migrasi jika perubahan tersebut merupakan perubahan yang tidak kompatibel. Idealnya, flag harus tersedia dalam setidaknya satu rilis utama.
• Untuk commit yang menghapus flag, gunakan Fixes #abc dalam deskripsi sehingga masalah GitHub akan ditutup saat commit digabungkan.