Panduan untuk meluncurkan perubahan yang dapat menyebabkan gangguan

Laporkan masalah Lihat sumber Nightly · 7.4 .

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

  1. Ikuti kebijakan dokumen desain.

  2. Laporkan masalah GitHub.

  3. Terapkan perubahan.

  4. Memperbarui label

  5. Balik flag 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. 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 tanda 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,
      },

Dalam deskripsi commit, tambahkan ringkasan singkat flag tersebut. Tambahkan juga RELNOTES: dalam bentuk berikut: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

Commit juga harus mengupdate dokumentasi yang relevan sehingga tidak ada periode commit yang kodenya tidak konsisten dengan dokumen. Karena dokumentasi kami sudah 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 ditemukan masalah pada tanda tersebut dan pengguna belum diharapkan melakukan migrasi: hapus tanda migration-ready.

Jika Anda berencana untuk membalikkan tanda dalam 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 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.

Memigrasikan project di pipeline downstream BUKAN sepenuhnya tanggung jawab penulis perubahan yang tidak kompatibel. Namun, Anda dapat melakukan hal berikut untuk mempercepat migrasi dan memudahkan hidup pengguna Bazel dan Bazel Green Team.

  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).

Mengibarkan bendera

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

  • Repositori inti di ekosistem dimigrasikan.

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

  • Masalah dan pertanyaan pengguna telah kami selesaikan.

Saat tanda siap dibalik di Bazel, tetapi diblokir pada migrasi internal di Google, pertimbangkan untuk menyetel nilai tanda ke false dalam file blazerc internal untuk membatalkan pemblokiran pembalikan tanda. Dengan melakukan hal ini, kita dapat memastikan pengguna Bazel bergantung pada perilaku baru secara default sedini mungkin.

Saat mengubah tanda default ke benar (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 di bagian deskripsi commit lainnya.
  • Gunakan Fixes #xyz dalam deskripsi agar masalah GitHub ditutup saat commit digabungkan.
  • Tinjau dan perbarui dokumentasi jika perlu.
  • 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 bermigrasi jika ini adalah perubahan besar yang 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.