Panduan untuk meluncurkan perubahan yang dapat menyebabkan gangguan

Laporkan masalah Lihat sumber

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.

  1. Ikuti kebijakan dokumen desain.

  2. Laporkan masalah di GitHub.

  3. Terapkan perubahan.

  4. Memperbarui label.

  5. Update repositori.

  6. Balik flag yang tidak kompatibel.

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:

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

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

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

  1. Kirim PR untuk memperbaiki project downstream.

  2. 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 bawah The 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.