Panduan untuk meluncurkan perubahan yang dapat menyebabkan gangguan

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Kami pasti akan membuat perubahan yang dapat menyebabkan gangguan 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 menerapkan kebijakan kompatibilitas mundur. Dokumen ini menjelaskan proses bagi kontributor Bazel untuk membuat perubahan yang merusak di Bazel agar mematuhi kebijakan ini.

  1. Ikuti kebijakan dokumen desain.

  2. Laporkan masalah GitHub.

  3. Terapkan perubahan.

  4. Perbarui label.

  5. Perbarui repositori.

  6. Balikkan flag yang tidak kompatibel.

Masalah GitHub

Laporkan masalah GitHub di repositori Bazel. Lihat contoh.

Sebaiknya:

  • Judul dimulai dengan nama tanda (nama tanda 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 mencakup contoh pesan error yang akan didapatkan 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 tanda yang tidak kompatibel.

Untuk alat migrasi, pertimbangkan untuk berkontribusi pada Buildifier. Fitur ini dapat menerapkan perbaikan otomatis pada file BUILD, WORKSPACE, dan .bzl. Linter juga dapat melaporkan peringatan.

Penerapan

Buat tanda baru di Bazel. Nilai default harus salah (false). Teks bantuan harus berisi URL masalah GitHub. Karena nama tanda dimulai dengan incompatible_, tanda tersebut memerlukan tag metadata:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

Di deskripsi commit, tambahkan ringkasan singkat tentang tanda. Tambahkan juga RELNOTES: dalam formulir berikut: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

Penerapan juga harus memperbarui dokumentasi yang relevan, sehingga tidak ada jeda penerapan yang membuat 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 membalikkan tanda di rilis utama berikutnya, tambahkan label `breaking-change-X.0" ke masalah.

Memperbarui repositori

Pengujian CI Bazel menguji daftar project penting di Bazel@HEAD + Downstream. Sebagian besar di antaranya sering menjadi dependensi proyek Bazel lainnya, sehingga penting untuk memigrasikannya agar tidak menghalangi migrasi bagi 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 ini ke masalah GitHub, mereka akan menangani hal berikut:

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

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

  3. Tindak lanjuti untuk memastikan semua masalah telah ditangani sebelum tanggal rilis target

Memigrasikan project di pipeline hilir 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. Kirim PR untuk memperbaiki project downstream.

  2. Hubungi komunitas Bazel untuk mendapatkan bantuan terkait migrasi (misalnya, SIG Pembuat Aturan Bazel).

Membalikkan tanda

Sebelum mengubah nilai default flag menjadi benar, 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 telah diperbaiki/ditutup.

  • Kekhawatiran dan pertanyaan pengguna telah diselesaikan.

Jika tanda siap diubah di Bazel, tetapi diblokir karena migrasi internal di Google, pertimbangkan untuk menyetel nilai tanda ke salah (false) di file blazerc internal untuk membatalkan pemblokiran perubahan tanda. Dengan melakukannya, kami dapat memastikan pengguna Bazel bergantung pada perilaku baru secara default sesegera mungkin.

Saat mengubah default tanda ke 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 lain deskripsi commit.
  • Gunakan Fixes #xyz dalam deskripsi, sehingga masalah GitHub akan ditutup saat commit digabungkan.
  • Tinjau dan perbarui dokumentasi jika diperlukan.
  • Buat masalah baru #abc untuk melacak penghapusan tanda.

Menghapus tanda

Setelah tanda diubah di HEAD, tanda tersebut akan dihapus dari Bazel pada akhirnya. Saat Anda berencana menghapus tanda tidak kompatibel:

  • Pertimbangkan untuk memberikan lebih banyak waktu bagi pengguna untuk bermigrasi jika perubahan yang tidak kompatibel bersifat signifikan. Idealnya, tanda harus tersedia dalam setidaknya satu rilis utama.
  • Untuk commit yang menghapus tanda, gunakan Fixes #abc dalam deskripsi agar masalah GitHub ditutup saat commit digabungkan.