Jika Anda berencana menambah, mengubah, atau menghapus fitur yang ditampilkan kepada pengguna, perubahan arsitektur yang signifikan pada Bazel, Anda harus menulis desain dokumen dan minta perubahan tersebut ditinjau sebelum Anda 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 lainnya 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 memberikan efek menyeluruh pada performa atau memori Bazel penggunaan (baik atau buruk)
- Perubahan pada API internal yang banyak digunakan
- Perubahan pada flag dan antarmuka command line.
Alasan peninjauan desain
Saat menulis dokumen desain, Anda bisa berkoordinasi dengan pengembang Bazel lainnya dan minta bimbingan dari tim inti Bazel. Misalnya, ketika proposal menambahkan, menghapus, atau mengubah fungsi atau objek apa pun yang tersedia di 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 konsekuensi global yang signifikan.
- Tim mendapatkan banyak permintaan fitur dari pengguna; permintaan semacam itu harus dievaluasi tidak hanya untuk kelayakan teknis tetapi juga kepentingannya permintaan fitur lainnya.
- Fitur Bazel sering diterapkan oleh orang-orang di luar tim inti; kontributor tersebut memiliki berbagai tingkat keahlian Bazel.
- Tim Bazel sendiri memiliki berbagai tingkat keahlian; tidak ada satu anggota tim memiliki pemahaman lengkap tentang setiap sudut Bazel.
- Perubahan pada Bazel harus mempertimbangkan kompatibilitas mundur dan menghindari kerusakan perubahan.
Kebijakan tinjauan desain Bazel membantu memaksimalkan kemungkinan bahwa:
- semua permintaan fitur mendapatkan tingkat pengawasan dasar.
- orang yang tepat akan mempertimbangkan desain sebelum kita berinvestasi pada sebuah implementasi yang mungkin tidak berhasil.
Untuk membantu Anda memulai, lihat dokumen desain di Repositori Proposal Bazel. Desain sedang dalam proses, sehingga detail implementasi dapat berubah dari waktu ke waktu dan dengan masukan. Dokumen desain yang diterbitkan menangkap desain awal, dan bukan perubahan berkelanjutan saat desain diterapkan. Selalu buka dokumentasi untuk deskripsi fungsi Bazel saat ini.
Alur Kerja Kontributor
Sebagai kontributor, Anda bisa menulis dokumen desain, mengirim permintaan pull, dan meminta peninjau untuk proposal Anda.
Menulis dokumen desain
Semua dokumen desain harus memiliki header yang menyertakan:
- author
- tanggal perubahan besar terakhir
- daftar peninjau, termasuk satu (dan hanya satu) peninjau utama
- status saat ini (draf, sedang ditinjau, disetujui, ditolak, yang diimplementasikan, diimplementasikan)
- link ke rangkaian diskusi (akan ditambahkan setelah pengumuman)
Dokumen dapat ditulis baik sebagai Dokumen Google yang dapat dibaca semua orang atau menggunakan Markdown. Baca di bawah tentang Perbandingan markup / Google Dokumen.
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. Tambah {i>file<i} {i>markdown<i} Anda atau tautan dokumen ke PR Anda.
Jika memungkinkan, pilih peninjau prospek. dan Cc peninjau lainnya. Jika Anda tidak memilih {i>lead reviewer<i}, pengelola akan menugaskannya untuk pekerjaan Humas Anda.
Setelah Anda membuat PR, peninjau dapat memberikan komentar awal selama peninjauan kode. Misalnya, {i>lead peninjau<i} bisa menyarankan {i>reviewer <i}tambahan, atau menunjukkan informasi yang hilang. {i>Lead peninjau <i}menyetujui permintaan Humas ketika mereka percaya bahwa proses peninjauan dapat dimulai. Bukan berarti proposalnya sempurna atau akan disetujui; itu berarti bahwa proposal itu berisi cukup informasi untuk memulai diskusi.
Mengumumkan proposal baru
Kirim pengumuman ke bazel-dev saat menyampaikan PR.
Anda dapat menyalin grup lain (misalnya, diskusi-bazel, untuk mendapatkan masukan dari pengguna akhir Bazel).
Melakukan iterasi dengan peninjau
Siapa pun yang tertarik dapat mengomentari proposal Anda. Cobalah untuk menjawab berbagai pertanyaan, mengklarifikasi proposal, dan mengatasi masalah.
Diskusi harus dilakukan di rangkaian pesan pengumuman. Jika proposal berada dalam Google Dokumen, komentar dapat digunakan sebagai gantinya (Perlu diketahui bahwa komentar anonim diizinkan).
Memperbarui status
Buat Humas baru untuk memperbarui status proposal, ketika iterasi selesai. Kirim PR ke peninjau utama yang sama dan Cc peninjau lainnya.
Untuk menerima proposal secara resmi, peninjau utama menyetujui permintaan Humas setelah memastikan bahwa peninjau lain setuju dengan keputusan tersebut.
Harus ada setidaknya 1 minggu antara pengumuman pertama dan persetujuan proposal. Ini memastikan bahwa pengguna memiliki cukup waktu untuk membaca dokumen dan menyampaikan kekhawatiran mereka.
Implementasi dapat dimulai sebelum proposal diterima, misalnya sebagai bukti konsep atau sebuah eksperimen. Namun, Anda tidak dapat mengirimkan perubahan sebelum peninjauan selesai.
Memilih peninjau prospek
Peninjau prospek harus merupakan pakar domain yang:
- Memiliki pengetahuan tentang subsistem yang relevan
- Bersifat objektif dan mampu memberikan umpan balik yang konstruktif
- Tersedia untuk seluruh periode peninjauan guna memimpin proses
Pertimbangkan untuk memeriksa kontak untuk berbagai tim label.
Markdown vs Google Dokumen
Putuskan mana yang paling sesuai untuk Anda, karena keduanya diterima.
Manfaat menggunakan Google Dokumen:
- Efektif untuk {i>brainstorming<i}, karena mudah untuk memulainya.
- Pengeditan kolaboratif.
- Iterasi cepat.
- Cara mudah untuk menyarankan pengeditan.
Manfaat menggunakan {i>file<i} Markdown:
- Bersihkan URL untuk penautan.
- Rekaman revisi eksplisit.
- Jangan lupa untuk menyiapkan hak akses sebelum memublikasikan link.
- Mudah ditelusuri dengan mesin telusur.
- Siap menghadapi masa depan: Teks biasa tidak dapat digunakan dengan alat tertentu dan tidak memerlukan koneksi Internet.
- Anda dapat memperbaruinya meskipun penulisnya tidak ada lagi.
- Link tersebut dapat diproses secara otomatis (memperbarui/mendeteksi link yang tidak aktif, mengambil daftar penulis, dll.).
Anda dapat memilih untuk melakukan iterasi terlebih dahulu di Google Dokumen, lalu mengonversinya menjadi Markdown untuk anak cucu.
Menggunakan Google Dokumen
Agar konsisten, gunakan template dokumen desain Bazel. {i>Wireframe<i} ini mencakup {i>header<i} yang diperlukan dan membuat visualisasi konsistensi dengan dokumen lain yang terkait dengan Bazel. Untuk melakukannya, klik File > Buat salinan atau klik link ini untuk membuat salinan dokumen desain template.
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 berkomentar secara anonim, bahkan tanpa akun Google.
Menggunakan Markdown
Dokumen disimpan di GitHub dan menggunakan Rasa GitHub dari Markdown (Spesifikasi).
Buat Humas untuk memperbarui dokumen yang ada. Perubahan yang signifikan harus ditinjau oleh {i>reviewer <i}dokumen. Perubahan sepele (seperti salah ketik, pemformatan) dapat disetujui oleh siapa saja.
Alur kerja peninjau
{i>Review<i} memberi komentar, mengulas, 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 peninjauan.
Saat Anda menerima proposal baru
- Lihat sekilas dokumen tersebut.
- Beri komentar jika informasi penting tidak ada, atau jika desain tidak sesuai dengan tujuan proyek.
- Menyarankan peninjau tambahan.
- Menyetujui Humas jika sudah siap ditinjau.
Selama proses peninjauan
- Terlibat dalam dialog dengan penulis desain tentang masalah yang bermasalah atau memerlukan klarifikasi.
- Jika sesuai, undanglah komentar dari non-{i>reviewer<i} yang harus mengetahui dari desain.
- Tentukan komentar mana yang harus ditangani oleh penulis sebagai prasyarat untuk persetujuan.
- Tulis "LGTM" (Looks Good To Me) dalam rangkaian diskusi saat Anda sedang puas dengan kondisi proposal saat ini.
Ikuti proses ini untuk semua permintaan peninjauan desain. Tidak menyetujui desain memengaruhi Bazel jika mereka tidak berada dalam indeks desain.
Tanggung jawab {i>Lead peninjau<i}
Anda bertanggung jawab untuk membuat keputusan go / no-go terkait penerapan dari desain yang tertunda. Jika Anda tidak dapat melakukannya, Anda harus mengidentifikasi delegasi yang sesuai (menugaskan kembali PR ke delegasi), atau tetapkan ulang bug ke Pengelola Bazel untuk disposisi lebih lanjut.
Selama proses peninjauan
- Memastikan proses iterasi komentar dan desain berjalan maju secara konstruktif.
- Sebelum persetujuan, pastikan bahwa kekhawatiran dari peninjau lain telah diselesaikan.
Setelah persetujuan oleh semua peninjau
- Pastikan sudah ada setidaknya 1 minggu sejak pengumuman pada milis.
- Pastikan PR memperbarui statusnya.
- Menyetujui PR yang dikirim oleh penulis proposal.
Menolak desain
- Memastikan penulis Humas mengirim PR; atau kirimkan PR.
- Humas akan memperbarui status dokumen tersebut.
- Tambahkan komentar ke dokumen yang menjelaskan mengapa desain tidak dapat disetujui statusnya saat ini, dan menjelaskan langkah selanjutnya, jika ada (seperti "memeriksa ulang halaman asumsi dan mengirimkannya kembali").