Jika berencana untuk menambahkan, mengubah, atau menghapus fitur yang dilihat 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 memiliki efek pervasif pada performa Bazel atau penggunaan memori (untuk lebih baik atau lebih buruk)
- Perubahan pada API internal yang banyak digunakan
- Perubahan pada tanda dan antarmuka command line.
Alasan peninjauan desain
Saat menulis dokumen desain, Anda dapat berkoordinasi dengan developer Bazel lainnya dan mencari 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 dikirim 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 semacam ini perlu dievaluasi tidak hanya untuk kelayakan teknis, tetapi juga terkait dengan permintaan fitur lainnya.
- Fitur Bazel sering diterapkan oleh orang di luar tim inti; kontributor tersebut memiliki tingkat keahlian Bazel yang sangat bervariasi.
- Tim Bazel sendiri memiliki berbagai tingkat keahlian; tidak ada satu anggota tim yang memiliki pemahaman menyeluruh tentang setiap sudut Bazel.
- Perubahan pada Bazel harus memperhitungkan kompatibilitas mundur dan menghindari perubahan yang dapat menyebabkan gangguan.
Kebijakan ulasan desain Bazel membantu memaksimalkan kemungkinan bahwa:
- semua permintaan fitur mendapatkan tingkat pemeriksaan dasar.
- orang yang tepat akan mempertimbangkan desainnya sebelum menggunakan investasi 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 mengambil desain awal, dan bukan perubahan berkelanjutan 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 Anda.
Menulis dokumen desain
Semua dokumen desain harus memiliki header yang mencakup:
- pengarang
- tanggal perubahan besar terakhir
- daftar pengulas, 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 di seluruh dunia atau menggunakan Markdown. Baca perbandingan Markdown/Google Dokumen di bawah.
Proposal yang memiliki dampak agar terlihat oleh pengguna harus memiliki bagian yang mendokumentasikan dampak terhadap kompatibilitas mundur (dan rencana peluncuran jika diperlukan).
Membuat Permintaan Pull
Bagikan dokumen desain dengan membuat permintaan pull (pull request/PR) untuk menambahkan dokumen tersebut ke indeks desain. Tambahkan file markdown atau link dokumen ke PR Anda.
Jika memungkinkan, pilih peninjau prospek. dan CC peninjau lainnya. Jika Anda tidak memilih peninjau utama, pengelola Bazel akan menetapkannya ke PR Anda.
Setelah Anda membuat PR, peninjau dapat membuat komentar awal selama peninjauan kode. Misalnya, peninjau prospek dapat menyarankan pengulas tambahan, atau menunjukkan informasi yang tidak lengkap. Peninjau prospek menyetujui PR ketika mereka percaya bahwa proses peninjauan dapat dimulai. Ini bukan berarti proposal tersebut sempurna atau akan disetujui; artinya proposal berisi informasi yang cukup untuk memulai diskusi.
Mengumumkan 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).
Lakukan iterasi dengan peninjau
Siapa saja yang tertarik dapat mengomentari proposal Anda. Coba jawab pertanyaan, jelaskan proposal, dan atasi masalah.
Diskusi harus dilakukan di rangkaian pesan pengumuman. Jika proposal berada di Google Dokumen, komentar dapat digunakan (Perhatikan bahwa komentar anonim diizinkan).
Memperbarui status
Buat PR baru untuk memperbarui status proposal, saat iterasi selesai. Kirim PR kepada peninjau utama yang sama dan CC peninjau lainnya.
Untuk menyetujui proposal secara resmi, peninjau prospek menyetujui PR setelah memastikan peninjau lain setuju dengan keputusan tersebut.
Setidaknya harus ada 1 minggu antara pengumuman pertama dan persetujuan proposal. Hal ini memastikan bahwa pengguna memiliki cukup waktu untuk membaca dokumen dan menyampaikan kekhawatirannya.
Penerapan dapat dimulai sebelum proposal diterima, misalnya sebagai bukti konsep atau eksperimen. Namun, Anda tidak dapat mengirimkan perubahan sebelum peninjauan selesai.
Memilih peninjau prospek
Reviewer prospek harus merupakan pakar domain yang:
- Pengetahuan tentang subsistem yang relevan
- Objektif dan mampu memberikan masukan yang membangun
- Tersedia selama keseluruhan periode peninjauan untuk memimpin proses
Pertimbangkan untuk memeriksa kontak untuk berbagai label tim.
Markdown vs Google Dokumen
Tentukan yang paling sesuai bagi Anda karena keduanya diterima.
Manfaat menggunakan Google Dokumen:
- Efektif untuk berdiskusi, karena mudah untuk memulainya.
- Pengeditan kolaboratif.
- Iterasi cepat.
- Cara mudah untuk menyarankan pengeditan.
Manfaat menggunakan file Markdown:
- Hapus URL untuk penautan.
- Catatan eksplisit revisi.
- Tidak lupa menyiapkan hak akses sebelum memublikasikan link.
- Mudah ditelusuri dengan mesin telusur.
- Future-proof: Teks biasa tidak bergantung pada alat tertentu apa pun dan tidak memerlukan koneksi Internet.
- Anda dapat memperbaruinya meskipun penulis tidak ada lagi.
- Link ini dapat diproses secara otomatis (memperbarui/mendeteksi link mati, mengambil daftar penulis, dll.).
Anda dapat memilih untuk melakukan iterasi pertama di Dokumen Google, lalu mengonversinya menjadi Markdown untuk masa mendatang.
Menggunakan Google Dokumen
Agar konsisten, gunakan template dokumen desain Bazel. Rilis 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 semua orang, klik Bagikan > Lanjutan > Ubah..., dan pilih "Aktif - Siapa saja yang memiliki link". Jika Anda mengizinkan komentar pada dokumen, siapa pun dapat mengomentari secara anonim, meskipun tanpa akun Google.
Menggunakan Markdown
Dokumen disimpan di GitHub dan menggunakan ragam GitHub Markdown (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
Pengulas mengomentari, 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 dokumen dengan cepat.
- Beri komentar jika informasi penting tidak ada, atau jika desain tidak sesuai dengan sasaran project.
- Sarankan pengulas tambahan.
- Setujui PR ketika sudah siap untuk ditinjau.
Selama proses peninjauan
- Jalin dialog dengan penulis desain tentang masalah yang menimbulkan masalah atau memerlukan klarifikasi.
- Jika memungkinkan, undang komentar dari non-pengulas yang harus mengetahui desainnya.
- Menentukan komentar yang harus ditangani oleh penulis sebagai prasyarat persetujuan.
- Tulis "LGTM" (Looks Good To Me) di thread 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 go / no-go terkait penerapan desain yang tertunda. Jika Anda tidak dapat melakukannya, Anda harus mengidentifikasi delegasi yang sesuai (menetapkan ulang PR kepada delegasi), atau menetapkan ulang bug ke pengelola Bazel untuk disposisi lebih lanjut.
Selama proses peninjauan
- Pastikan bahwa proses iterasi komentar dan desain berjalan maju secara konstruktif.
- Sebelum disetujui, pastikan masalah dari peninjau lain telah diselesaikan.
Setelah persetujuan oleh semua peninjau
- Pastikan setidaknya ada 1 minggu sejak pengumuman di milis.
- Pastikan PR memperbarui status.
- Setujui PR yang dikirim oleh penulis proposal.
Menolak desain
- Pastikan penulis PR mengirimkan PR; atau kirimkan PR.
- PR memperbarui status dokumen.
- Tambahkan komentar ke dokumen yang menjelaskan mengapa desain tidak dapat disetujui dalam statusnya saat ini, dan menguraikan langkah selanjutnya, jika ada (seperti "kunjungi ulang asumsi tidak valid dan kirim ulang").