Dokumen ini ditujukan untuk kontributor Bazel.
Deskripsi commit di Bazel mencakup tag RELNOTES: yang diikuti dengan catatan rilis. Hal ini digunakan oleh tim Bazel untuk melacak perubahan di setiap rilis dan menulis
pengumuman rilis.
Ringkasan
Apakah perubahan Anda adalah perbaikan bug? Dalam hal ini, Anda tidak memerlukan catatan rilis. Harap sertakan referensi ke masalah GitHub.
Jika perubahan menambahkan / menghapus / mengubah Bazel dengan cara yang terlihat oleh pengguna, maka sebaiknya perubahan tersebut disebutkan.
Jika perubahannya signifikan, ikuti kebijakan dokumen desain terlebih dahulu.
Panduan
Catatan rilis akan dibaca oleh pengguna kami, jadi harus singkat (ideal satu kalimat), hindari jargon (terminologi internal Bazel), dan harus berfokus pada perubahan yang dilakukan.
Sertakan link ke dokumentasi yang relevan. Hampir semua catatan rilis harus berisi link. Jika deskripsi menyebutkan tanda, fitur, nama perintah, pengguna mungkin ingin mengetahui lebih lanjut tentang hal tersebut.
Gunakan tanda petik terbalik di sekitar kode, simbol, flag, atau kata apa pun yang berisi garis bawah.
Jangan hanya menyalin dan menempelkan deskripsi bug. Pesan error sering kali tidak jelas dan hanya dapat dipahami oleh kami, sehingga membuat pengguna bingung. Catatan rilis dimaksudkan untuk menjelaskan apa yang telah berubah dan alasannya dalam bahasa yang mudah dipahami pengguna.
Selalu gunakan bentuk waktu sekarang dan format "Bazel kini mendukung Y" atau "X kini melakukan Z". Kami tidak ingin catatan rilis kami terdengar seperti entri bug. Semua entri catatan rilis harus informatif dan menggunakan gaya serta bahasa yang konsisten.
Jika sesuatu telah dihentikan atau dihapus, gunakan "X telah dihentikan" atau "X telah dihapus". Bukan "dihapus" atau "telah dihapus".
Jika Bazel sekarang melakukan sesuatu yang berbeda, gunakan "X sekarang $newBehavior, bukan $oldBehavior" dalam bentuk present tense. Hal ini memungkinkan pengguna mengetahui secara mendetail apa yang dapat mereka harapkan saat menggunakan rilis baru.
Jika Bazel kini mendukung atau tidak lagi mendukung sesuatu, gunakan "Bazel kini mendukung/tidak lagi mendukung X".
Jelaskan alasan sesuatu dihapus / tidak digunakan lagi / diubah. Satu kalimat sudah cukup, tetapi kami ingin pengguna dapat mengevaluasi dampak pada build mereka.
JANGAN menjanjikan fungsionalitas pada masa mendatang. Hindari "bendera ini akan dihapus" atau "ini akan diubah". Hal ini menimbulkan ketidakpastian. Hal pertama yang akan ditanyakan pengguna adalah "kapan?" dan kita tidak ingin mereka mulai mengkhawatirkan build saat ini akan rusak pada waktu yang tidak diketahui.
Proses
Sebagai bagian dari proses
rilis,
kami mengumpulkan tag RELNOTES dari setiap commit. Kita menyalin semuanya di Dokumen Google tempat kita meninjau, mengedit, dan mengatur catatan.
Pengelola rilis mengirim email ke milis bazel-dev. Kontributor Bazel diundang untuk berkontribusi pada dokumen dan memastikan perubahan mereka tercermin dengan benar dalam pengumuman.
Selanjutnya, pengumuman akan dikirimkan ke blog Bazel, menggunakan repositori bazel-blog.