Jika Anda berencana menambahkan, mengubah, atau menghapus fitur yang terlihat oleh pengguna, atau melakukan perubahan arsitektur yang signifikan pada Bazel, Anda harus menulis dokumen desain dan meninjaunya sebelum dapat mengirimkan perubahan.
Berikut beberapa contoh perubahan signifikan:
- Penambahan atau penghapusan aturan build native
- Perubahan yang dapat menyebabkan gangguan pada aturan native
- Perubahan pada semantik aturan build native yang memengaruhi perilaku lebih dari satu aturan
- Perubahan pada API definisi aturan Bazel
- Perubahan pada API yang digunakan Bazel untuk terhubung ke sistem lain
- Perubahan pada bahasa, semantik, atau API Starlark
- Perubahan yang dapat berdampak luas pada performa atau penggunaan memori Bazel (baik atau buruk)
- Perubahan pada API internal yang banyak digunakan
- Perubahan pada tanda dan antarmuka command line.
Alasan untuk peninjauan desain
Saat menulis dokumen desain, Anda dapat berkoordinasi dengan developer Bazel lainnya dan meminta panduan dari tim inti Bazel. Misalnya, saat proposal menambahkan, menghapus, atau mengubah fungsi atau objek apa pun yang tersedia di file BUILD, MODULE.bazel, atau bzl, tambahkan tim Starlark sebagai peninjau. Dokumen desain ditinjau sebelum dikirimkan karena:
- Bazel adalah sistem yang sangat kompleks; perubahan lokal yang tampak tidak berbahaya dapat memiliki konsekuensi global yang signifikan.
- Tim menerima banyak permintaan fitur dari pengguna; permintaan tersebut perlu dievaluasi tidak hanya dari kelayakan teknisnya, tetapi juga kepentingannya dibandingkan dengan permintaan fitur lainnya.
- Fitur Bazel sering diimplementasikan oleh orang-orang di luar tim inti; kontributor tersebut memiliki tingkat keahlian Bazel yang sangat bervariasi.
- Tim Bazel sendiri memiliki tingkat keahlian yang berbeda-beda; tidak ada satu pun anggota tim yang memahami sepenuhnya setiap sudut Bazel.
- Perubahan pada Bazel harus memperhitungkan kompatibilitas mundur dan menghindari perubahan yang merusak.
Kebijakan peninjauan desain Bazel membantu memaksimalkan kemungkinan bahwa:
- Semua permintaan fitur akan mendapatkan tingkat pemeriksaan dasar.
- orang yang tepat akan memberikan masukan tentang desain sebelum kami berinvestasi dalam penerapan yang mungkin tidak berhasil.
Untuk membantu Anda memulai, lihat dokumen desain di Bazel Proposals Repository. Desain masih dalam proses, sehingga detail penerapan dapat berubah dari waktu ke waktu dan berdasarkan masukan. Dokumen desain yang dipublikasikan mencatat desain awal, dan bukan perubahan yang sedang berlangsung saat desain diterapkan. Selalu buka dokumentasi untuk mengetahui deskripsi fungsi Bazel saat ini.
Alur Kerja Kontributor
Sebagai kontributor, Anda dapat menulis dokumen desain, mengirim permintaan pull, dan meminta peninjau untuk proposal Anda.
Menulis dokumen desain
Semua dokumen desain harus memiliki header yang mencakup:
- author
- tanggal perubahan besar terakhir
- daftar peninjau, termasuk satu (dan hanya satu) peninjau utama
- status saat ini (draf, dalam peninjauan, disetujui, ditolak, sedang diterapkan, diterapkan)
- link ke rangkaian pesan diskusi (akan ditambahkan setelah pengumuman)
Dokumen dapat ditulis sebagai Dokumen Google yang dapat dibaca oleh siapa saja atau menggunakan Markdown. Baca di bawah tentang Perbandingan Markdown / Google Dokumen.
Proposal yang memiliki dampak yang terlihat oleh pengguna harus memiliki bagian yang mendokumentasikan dampak pada kompatibilitas mundur (dan rencana peluncuran jika diperlukan).
Membuat Permintaan Tarik
Bagikan dokumen desain Anda dengan membuat pull request (PR) untuk menambahkan dokumen ke indeks desain. Tambahkan file markdown atau link dokumen ke PR Anda.
Jika memungkinkan, pilih peninjau utama. dan cc peninjau lainnya. Jika Anda tidak memilih peninjau utama, pengelola Bazel akan menetapkannya untuk PR Anda.
Setelah Anda membuat PR, peninjau dapat memberikan komentar awal selama peninjauan kode. Misalnya, peninjau utama dapat menyarankan peninjau tambahan, atau menunjukkan informasi yang tidak ada. Peninjau utama menyetujui PR saat mereka yakin bahwa proses peninjauan dapat dimulai. Hal ini tidak berarti proposal tersebut sempurna atau akan disetujui; hal ini berarti proposal tersebut berisi informasi yang cukup untuk memulai diskusi.
Mengumumkan usulan baru
Kirim pengumuman ke bazel-dev saat PR dikirimkan.
Anda dapat menyalin grup lain (misalnya, bazel-discuss, untuk mendapatkan masukan dari pengguna akhir Bazel).
Melakukan iterasi dengan peninjau
Siapa pun yang tertarik dapat mengomentari proposal Anda. Coba jawab pertanyaan, perjelas proposal, dan atasi masalah.
Diskusi harus dilakukan di rangkaian pesan pengumuman. Jika proposal ada di Dokumen Google, komentar dapat digunakan sebagai gantinya (Perhatikan bahwa komentar anonim diizinkan).
Perbarui status
Buat PR baru untuk memperbarui status proposal, saat iterasi selesai. Kirim PR ke peninjau utama yang sama dan teruskan email ke peninjau lainnya.
Untuk menerima proposal secara resmi, peninjau utama menyetujui PR setelah memastikan bahwa peninjau lain menyetujui keputusan tersebut.
Setidaknya harus ada waktu 1 minggu antara pengumuman pertama dan persetujuan proposal. Hal ini memastikan bahwa pengguna memiliki cukup waktu untuk membaca dokumen dan menyampaikan kekhawatiran mereka.
Penerapan dapat dimulai sebelum proposal diterima, misalnya sebagai bukti konsep atau eksperimen. Namun, Anda tidak dapat mengirimkan perubahan sebelum peninjauan selesai.
Memilih peninjau utama
Peninjau utama harus merupakan pakar domain yang:
- Memahami subsistem yang relevan
- Objektif dan mampu memberikan masukan yang membangun
- Tersedia selama seluruh periode peninjauan untuk memimpin proses
Pertimbangkan untuk memeriksa kontak untuk berbagai label tim.
Markdown vs. Google Dokumen
Tentukan mana yang paling cocok untuk Anda, karena keduanya diterima.
Manfaat menggunakan Google Dokumen:
- Efektif untuk berdiskusi, karena mudah untuk memulai.
- Pengeditan kolaboratif.
- Iterasi cepat.
- Cara mudah untuk menyarankan pengeditan.
Manfaat menggunakan file Markdown:
- URL bersih untuk penautan.
- Catatan revisi eksplisit.
- Tidak lupa menyiapkan hak akses sebelum memublikasikan link.
- Mudah ditelusuri dengan mesin telusur.
- Siap untuk masa depan: Teks biasa tidak bergantung pada alat tertentu dan tidak memerlukan koneksi Internet.
- Anda dapat memperbaruinya meskipun penulisnya sudah tidak ada.
- File ini dapat diproses secara otomatis (memperbarui/mendeteksi link yang tidak aktif, mengambil daftar penulis, dll.).
Anda dapat memilih untuk melakukan iterasi terlebih dahulu pada Dokumen Google, lalu mengonversinya ke Markdown untuk arsip.
Menggunakan Google Dokumen
Untuk konsistensi, gunakan template dokumen desain Bazel. Dokumen ini mencakup header yang diperlukan dan menciptakan konsistensi visual dengan dokumen terkait Bazel lainnya. Untuk melakukannya, klik File > Buat salinan atau klik link ini untuk membuat salinan template dokumen desain.
Agar dokumen Anda dapat dibaca oleh siapa saja, klik Bagikan > Lanjutan > Ubah…, lalu pilih "Aktif - Siapa saja yang memiliki link". Jika Anda mengizinkan komentar pada dokumen, siapa pun dapat berkomentar secara anonim, bahkan tanpa Akun Google.
Menggunakan Markdown
Dokumen disimpan di GitHub dan menggunakan Markdown versi GitHub (Spesifikasi).
Buat PR untuk memperbarui dokumen yang ada. Perubahan signifikan harus ditinjau oleh peninjau dokumen. Perubahan kecil (seperti kesalahan ketik, pemformatan) dapat disetujui oleh siapa saja.
Alur kerja peninjau
Peninjau memberikan komentar, meninjau, dan menyetujui dokumen desain.
Tanggung jawab peninjau umum
Anda bertanggung jawab untuk meninjau dokumen desain, meminta informasi tambahan jika diperlukan, dan menyetujui desain yang lulus proses peninjauan.
Saat Anda menerima proposal baru
- Lihat sekilas dokumen.
- Berikan komentar jika informasi penting tidak ada, atau jika desain tidak sesuai dengan tujuan project.
- Sarankan peninjau tambahan.
- Setujui PR saat sudah siap untuk ditinjau.
Selama proses peninjauan
- Berpartisipasilah dalam dialog dengan penulis desain tentang masalah yang bermasalah atau memerlukan klarifikasi.
- Jika sesuai, undang komentar dari non-pengulas yang harus mengetahui desain tersebut.
- Tentukan komentar mana yang harus ditanggapi oleh penulis sebagai prasyarat untuk persetujuan.
- Tulis "LGTM" (Looks Good To Me) di rangkaian diskusi jika Anda puas dengan status proposal saat ini.
Ikuti proses ini untuk semua permintaan peninjauan desain. Jangan menyetujui desain yang memengaruhi Bazel jika tidak ada dalam indeks desain.
Tanggung jawab peninjau utama
Anda bertanggung jawab untuk membuat keputusan apakah akan menerapkan atau tidak desain yang tertunda. Jika Anda tidak dapat melakukannya, Anda harus mengidentifikasi delegasi yang sesuai (tetapkan ulang PR ke delegasi), atau tetapkan ulang bug ke pengelola Bazel untuk disposisi lebih lanjut.
Selama proses peninjauan
- Pastikan proses komentar dan iterasi desain berjalan secara konstruktif.
- Sebelum menyetujui, pastikan masalah dari peninjau lain telah diselesaikan.
Setelah disetujui oleh semua peninjau
- Pastikan sudah ada setidaknya 1 minggu sejak pengumuman di milis.
- Pastikan PR memperbarui status.
- Menyetujui PR yang dikirim oleh penulis proposal.
Menolak desain
- Pastikan penulis PR mengirimkan PR; atau kirimkan PR kepada mereka.
- PR memperbarui status dokumen.
- Tambahkan komentar ke dokumen yang menjelaskan alasan desain tidak dapat disetujui dalam kondisi saat ini, dan menguraikan langkah selanjutnya, jika ada (seperti "tinjau kembali asumsi yang tidak valid dan kirim ulang").