Panduan untuk meluncurkan perubahan yang dapat menyebabkan gangguan

Tidak dapat dihindari bahwa kami akan membuat perubahan yang dapat menyebabkan gangguan pada Bazel. Kita harus mengubah desain dan memperbaiki hal-hal yang kurang berfungsi. Namun, kami perlu memastikan bahwa ekosistem komunitas dan Bazel dapat mengikuti perkembangan. Oleh karena itu, project Bazel telah menerapkan kebijakan kompatibilitas mundur. Dokumen ini menjelaskan proses bagi kontributor Bazel untuk melakukan perubahan yang dapat menyebabkan gangguan di Bazel untuk mematuhi kebijakan ini.

  1. Ikuti kebijakan dokumen desain.

  2. Laporkan masalah GitHub.

  3. Terapkan perubahan.

  4. Memperbarui label

  5. Balik tanda yang tidak kompatibel.

Masalah GitHub

Ajukan masalah GitHub di repositori Bazel. Lihat contoh.

Sebaiknya:

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

  • Anda menambahkan label incompatible-change.

  • Deskripsi berisi deskripsi perubahan dan tautan ke dokumen desain yang relevan.

  • Deskripsi berisi resep migrasi, untuk menjelaskan kepada pengguna cara mereka memperbarui kode. Idealnya, jika perubahan bersifat mekanis, sertakan link ke alat migrasi.

  • Deskripsi tersebut 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 tersebut bermanfaat dan dapat ditindaklanjuti. Jika memungkinkan, pesan error harus menyertakan nama flag yang tidak kompatibel.

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

Penerapan

Buat tanda baru di Bazel. Nilai defaultnya harus salah. 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 formulir 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 dengan kode yang tidak konsisten dengan dokumen. Karena dokumentasi kami memiliki beberapa 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 tanda dan pengguna belum melakukan migrasi: hapus tanda migration-ready.

Jika Anda berencana untuk membalikkan flag pada rilis utama berikutnya, tambahkan label `breaking-change-X.0" ke masalah tersebut.

Mengupdate repositori

Bazel CI menguji daftar project penting di Bazel@HEAD + Downstream. Sebagian besar resource tersebut sering kali merupakan dependensi dari project Bazel lainnya. Oleh karena itu, penting untuk memigrasikannya guna menghentikan migrasi bagi komunitas yang lebih luas.

Untuk memantau status migrasi project tersebut, Anda dapat menggunakan pipeline bazelisk-plus-incompatible-flags, memeriksa cara kerja pipeline ini di sini.

Memigrasikan project di pipeline downstream BUKAN sepenuhnya merupakan tanggung jawab pembuat perubahan yang tidak kompatibel. Tetapi Anda dapat melakukan hal berikut untuk mempercepat migrasi dan mempermudah pengguna Bazel dan Tim Bazel Green.

  1. Laporkan masalah GitHub untuk memberi tahu pemilik project downstream yang rusak karena perubahan Anda yang tidak kompatibel.
  2. Mengirim PR untuk memperbaiki project downstream.
  3. Hubungi komunitas Bazel untuk mendapatkan bantuan terkait migrasi (misalnya Bazel Rules Authors SIG).

Membalik bendera

Sebelum membalik nilai default tanda ke benar (true), pastikan bahwa:

  • Repositori inti dalam ekosistem dimigrasikan.

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

  • Masalah dan pertanyaan pengguna telah diatasi.

Saat tanda siap dibalik di Bazel, tetapi diblokir saat migrasi internal di Google, harap pertimbangkan untuk menyetel nilai tanda ke salah dalam file blazerc internal untuk berhenti memblokir balik tanda. Dengan melakukan ini, kita dapat memastikan pengguna Bazel bergantung pada perilaku baru secara default seawal mungkin.

Saat mengubah flag default ke true, 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 sehingga masalah GitHub akan ditutup saat commit digabungkan.
  • Tinjau dan perbarui dokumentasi jika perlu.
  • Laporkan masalah baru #abc untuk melacak penghapusan tanda.

Menghapus tanda

Setelah flag dibalik ke HEAD, pada akhirnya flag harus juga dihapus dari Bazel. Jika Anda berencana menghapus tanda yang tidak kompatibel:

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