Jika Anda berencana menambahkan, mengubah, atau menghapus fitur yang ditampilkan kepada pengguna, atau membuat perubahan arsitektur yang signifikan pada Bazel, Anda harus menulis dokumen desain dan meninjaunya sebelum dapat mengirimkan perubahan.
Berikut beberapa contoh perubahan yang 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 Bazel atau penggunaan memori (baik atau buruk)
- Perubahan pada API internal yang banyak digunakan
- Perubahan pada flag dan antarmuka command line.
Alasan untuk peninjauan desain
Saat menulis dokumen desain, Anda dapat berkoordinasi dengan developer Bazel lainnya dan mendapatkan panduan dari tim inti Bazel. Misalnya, saat proposal menambahkan, menghapus, atau mengubah fungsi atau objek apa pun yang tersedia di file BUILD, WORKSPACE, atau bzl, tambahkan tim Starlark sebagai peninjau. Dokumen desain ditinjau sebelum diserahkan karena:
- Bazel adalah sistem yang sangat kompleks; perubahan lokal yang tampaknya tidak berbahaya dapat memiliki konsekuensi global yang signifikan.
- Tim mendapatkan banyak permintaan fitur dari pengguna; permintaan tersebut perlu dievaluasi tidak hanya untuk kelayakan teknis tetapi juga tingkat kepentingan sehubungan dengan permintaan fitur lainnya.
- Fitur Bazel sering diterapkan oleh orang-orang di luar tim inti; kontributor tersebut memiliki tingkat keahlian Bazel yang sangat beragam.
- Tim Bazel sendiri memiliki berbagai tingkat keahlian; tidak ada satu anggota tim yang memiliki pemahaman lengkap tentang setiap sudut Bazel.
- Perubahan pada Bazel harus memperhitungkan kompatibilitas mundur dan menghindari perubahan yang dapat menyebabkan gangguan.
Kebijakan peninjauan desain Bazel membantu memaksimalkan kemungkinan bahwa:
- semua permintaan fitur mendapatkan tingkat pemeriksaan dasar.
- orang yang tepat akan mempertimbangkan desain sebelum kita berinvestasi dalam implementasi yang mungkin tidak berhasil.
Untuk membantu Anda memulai, lihat dokumen desain di Repositori Proposal Bazel. Desain masih dalam proses, sehingga detail implementasi dapat berubah seiring waktu dan dengan masukan. Dokumen desain yang dipublikasikan menangkap desain awal, dan bukan perubahan yang sedang berlangsung saat desain diimplementasikan. Selalu buka dokumentasi untuk deskripsi fungsi Bazel saat ini.
Alur Kerja Kontributor
Sebagai kontributor, Anda dapat menulis dokumen desain, mengirim permintaan pull, dan meminta peninjau untuk proposal.
Menulis dokumen desain
Semua dokumen desain harus memiliki header yang menyertakan:
- author
- tanggal perubahan besar terakhir
- daftar peninjau, termasuk satu (dan hanya satu) peninjau prospek
- status saat ini (draf, sedang ditinjau, disetujui, ditolak, diterapkan, diterapkan)
- link ke rangkaian diskusi (akan ditambahkan setelah pengumuman)
Dokumen dapat ditulis sebagai Dokumen Google yang dapat dibaca semua orang atau menggunakan Markdown. Baca tentang Perbandingan Markdown / Google Dokumen di bawah ini.
Proposal yang memiliki dampak yang terlihat oleh pengguna harus memiliki bagian yang mendokumentasikan dampak terhadap kompatibilitas mundur (dan rencana peluncuran jika diperlukan).
Membuat Permintaan Pull
Bagikan dokumen desain Anda dengan membuat permintaan pull (PR) untuk menambahkan dokumen tersebut ke indeks desain. Tambahkan {i>file<i} markdown atau link dokumen ke tim Humas (PR).
Jika memungkinkan, pilih peninjau utama. dan cc peninjau lainnya. Jika Anda tidak memilih peninjau utama, pengelola Bazel akan menugaskannya untuk tim Humas Anda.
Setelah Anda membuat siaran pers, peninjau dapat membuat komentar awal selama peninjauan kode. Misalnya, peninjau utama dapat menyarankan peninjau tambahan, atau menunjukkan informasi yang tidak lengkap. Peninjau utama menyetujui PR saat mereka yakin bahwa proses peninjauan dapat dimulai. Hal ini tidak berarti bahwa proposal telah sempurna atau akan disetujui; itu berarti bahwa proposal berisi informasi yang cukup untuk memulai diskusi.
Umumkan proposal 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. Cobalah untuk menjawab pertanyaan, klarifikasi proposal, dan tangani masalah.
Diskusi harus dilakukan di thread pengumuman. Jika proposal ada di Google Dokumen, komentar dapat digunakan sebagai gantinya (Perlu diperhatikan bahwa komentar anonim diizinkan).
Perbarui status
Buat PR baru untuk memperbarui status proposal, saat iterasi selesai. Mengirim siaran pers ke peninjau prospek yang sama dan men-cc peninjau lainnya.
Untuk menerima proposal secara resmi, peninjau utama menyetujui PR setelah memastikan peninjau lain setuju dengan keputusan tersebut.
Harus ada setidaknya 1 minggu antara pengumuman pertama dan persetujuan proposal. Hal ini memastikan bahwa pengguna memiliki cukup waktu untuk membaca dokumen dan berbagi kekhawatiran mereka.
Implementasi dapat dimulai sebelum proposal diterima, misalnya sebagai bukti konsep atau eksperimen. Namun, Anda tidak dapat mengirimkan perubahan sebelum peninjauan selesai.
Memilih {i>lead review<i}
Pengulas prospek harus merupakan pakar domain yang:
- Memiliki pengetahuan tentang subsistem yang relevan
- Objektif dan mampu memberikan umpan balik yang konstruktif
- Tersedia untuk seluruh periode peninjauan untuk memimpin proses
Pertimbangkan untuk memeriksa kontak untuk berbagai label tim.
Markdown vs Google Dokumen
Putuskan mana yang terbaik untuk Anda, karena keduanya diterima.
Manfaat menggunakan Google Dokumen:
- Efektif untuk {i>brainstorming<i}, karena mudah untuk memulainya.
- Pengeditan kolaboratif.
- Iterasi yang cepat.
- Cara mudah untuk menyarankan pengeditan.
Manfaat menggunakan {i>file<i} Markdown:
- URL bersih untuk penautan.
- Data revisi eksplisit.
- Tidak lupa untuk menyiapkan hak akses sebelum memublikasikan link.
- Mudah ditelusuri dengan mesin telusur.
- Siap menghadapi masa depan: Teks biasa tidak dapat disimpan oleh alat tertentu dan tidak memerlukan koneksi Internet.
- Anda dapat memperbaruinya meskipun penulis tidak ada lagi.
- Link tersebut dapat diproses secara otomatis (memperbarui/mendeteksi link nonaktif, mengambil daftar penulis, dll.).
Anda dapat memilih untuk melakukan iterasi terlebih dahulu di Dokumen Google, lalu mengonversinya menjadi Markdown untuk masa depan.
Menggunakan Google Dokumen
Agar konsisten, gunakan Template dokumen desain Bazel. Fitur ini menyertakan header yang diperlukan dan menciptakan konsistensi visual dengan dokumen terkait Bazel lainnya. Untuk melakukannya, klik File > Make a copy atau klik link ini untuk membuat salinan template dokumen desain.
Agar dokumen Anda dapat dibaca oleh semua orang, klik Bagikan > Lanjutan > Ubah..., lalu pilih "Aktif - Siapa saja yang memiliki link". Jika Anda mengizinkan komentar pada dokumen, siapa saja dapat memberi komentar secara anonim, bahkan tanpa akun Google.
Menggunakan Markdown
Dokumen disimpan di GitHub dan menggunakan ragam GitHub dari Markdown (Spesifikasi).
Buat PR untuk memperbarui dokumen yang sudah ada. Perubahan signifikan harus ditinjau oleh peninjau dokumen. Perubahan sepele (seperti salah ketik, format) dapat disetujui oleh siapa saja.
Alur kerja peninjau
Peninjau mengomentari, meninjau dan menyetujui dokumen desain.
Tanggung jawab umum peninjau
Anda bertanggung jawab untuk meninjau dokumen desain, meminta informasi tambahan jika diperlukan, dan menyetujui desain yang lulus proses tinjauan.
Saat Anda menerima proposal baru
- Lihat sekilas dokumen tersebut.
- Beri komentar jika ada informasi penting, atau jika desain tidak sesuai dengan tujuan proyek.
- Sarankan peninjau tambahan.
- Setujui PR saat siap ditinjau.
Selama proses peninjauan
- Terlibat dalam dialog dengan penulis desain tentang masalah yang bermasalah atau memerlukan klarifikasi.
- Jika sesuai, mintalah komentar dari non-peninjau yang seharusnya mengetahui desain tersebut.
- Menentukan komentar yang harus ditangani oleh penulis sebagai prasyarat untuk persetujuan.
- Tulis "LGTM" (Looks Good To Me) di rangkaian diskusi jika Anda sudah puas dengan status proposal saat ini.
Ikuti proses ini untuk semua permintaan peninjauan desain. Jangan setujui desain yang memengaruhi Bazel jika tidak ada dalam indeks desain.
Tanggung jawab pimpinan peninjau
Anda bertanggung jawab untuk membuat keputusan tentang penerapan desain yang tertunda. Jika tidak dapat melakukannya, Anda harus mengidentifikasi delegasi yang sesuai (menetapkan kembali PR ke delegasi), atau menetapkan ulang bug kepada pengelola Bazel untuk disposisi lebih lanjut.
Selama proses peninjauan
- Pastikan proses iterasi desain dan komentar berjalan secara konstruktif.
- Sebelum disetujui, pastikan bahwa masalah dari peninjau lain telah diselesaikan.
Setelah disetujui oleh semua peninjau
- Pastikan sudah ada setidaknya 1 minggu sejak pengumuman di milis.
- Pastikan bagian Humas memperbarui statusnya.
- Menyetujui PR yang dikirim oleh penulis proposal.
Menolak desain
- Pastikan penulis PR mengirimkan siaran pers, atau mengirimkan siaran pers.
- Humas memperbarui status dokumen.
- Tambahkan komentar ke dokumen yang menjelaskan alasan desain tidak dapat disetujui dengan status saat ini, dan jelaskan langkah selanjutnya, jika ada (seperti "kunjungi kembali asumsi yang tidak valid dan kirim ulang").