Panduan untuk meluncurkan perubahan yang dapat menyebabkan gangguan

Laporkan masalah Lihat sumber Per Malam · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

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, kita perlu untuk memastikan komunitas dan ekosistem Bazel dapat mengikuti. Untuk itu, Bazel Project telah mengadopsi kebijakan kompatibilitas mundur. Dokumen ini menjelaskan proses bagi kontributor Bazel untuk membuat pelanggaran perubahan Bazel untuk mematuhi kebijakan ini.

  1. Ikuti kebijakan dokumen desain.

  2. Laporkan masalah GitHub.

  3. Terapkan perubahan.

  4. Perbarui label.

  5. Mengupdate repositori.

  6. Balik tanda yang tidak kompatibel.

Masalah GitHub

Laporkan masalah GitHub di repositori Bazel. Lihat contoh.

Sebaiknya:

  • Judulnya dimulai dengan nama penanda (nama penanda akan dimulai dengan incompatible_).

  • Anda menambahkan label incompatible-change

  • Deskripsi berisi deskripsi perubahan dan link ke informasi dokumen desain.

  • Deskripsi berisi urutan langkah migrasi, untuk menjelaskan kepada pengguna bagaimana mereka seharusnya memperbarui kode mereka. Idealnya, ketika perubahan itu mekanis, sertakan tautan ke migrasi sistem.

  • Deskripsi menyertakan contoh pesan {i>error<i} yang akan diterima pengguna jika dan tidak dimigrasikan. 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 project yang tidak kompatibel penanda.

Untuk alat migrasi, pertimbangkan untuk berkontribusi ke Pembuat. Aplikasi ini dapat menerapkan perbaikan otomatis ke file BUILD, WORKSPACE, dan .bzl. Halaman ini juga dapat melaporkan peringatan.

Penerapan

Buat tanda baru di Bazel. Nilai default harus false. Teks bantuan harus berisi URL masalah GitHub. Saat nama penanda dimulai dengan incompatible_, diperlukan tag metadata:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

Dalam deskripsi commit, tambahkan ringkasan singkat flag tersebut. 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 jendela commit dengan kode yang tidak konsisten dengan dokumen. Karena dokumentasi diversikan, perubahan pada dokumen tidak akan secara tidak sengaja dirilis sebelum waktunya.

Label

Setelah commit digabungkan dan perubahan yang tidak kompatibel sudah siap digunakan, tambahkan label migration-ready terhadap masalah GitHub.

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

Jika Anda berencana untuk membalikkan tanda dalam rilis utama berikutnya, tambahkan label `breaking-change-X.0" masalahnya.

Mengupdate repositori

Bazel CI menguji daftar proyek penting di Bazel@HEAD + Downstream. Kebanyakan dari mereka sering dependensi dari project Bazel lainnya, oleh karena itu, penting untuk memigrasikannya guna 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 ini ke masalah GitHub, mereka 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 Anda yang tidak kompatibel (lihat contoh)

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

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

  1. Mengirim PR untuk memperbaiki project downstream.

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

  • Semua masalah dalam checklist ditandai sebagai telah diperbaiki/ditutup.

  • 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 lain deskripsi commit.
  • Gunakan Fixes #xyz di deskripsi agar masalah GitHub dapat diselesaikan 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 untuk menghapus tanda 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 tanda, gunakan Fixes #abc dalam deskripsi sehingga masalah GitHub akan ditutup saat commit digabungkan.