Dokumen ini ditujukan untuk kontributor Bazel.
Deskripsi commit di Bazel menyertakan tag RELNOTES: yang diikuti dengan catatan rilis. Catatan ini digunakan oleh tim Bazel untuk melacak perubahan di setiap rilis dan menulis pengumuman rilis.
Ringkasan
Apakah perubahan Anda adalah perbaikan bug? Jika demikian, Anda tidak memerlukan catatan rilis. Sertakan referensi ke masalah GitHub.
Jika perubahan menambahkan / menghapus / mengubah Bazel dengan cara yang terlihat oleh pengguna, sebaiknya sebutkan perubahan tersebut.
Jika perubahannya signifikan, ikuti kebijakan dokumen desain terlebih dahulu.
Panduan
Catatan rilis akan dibaca oleh pengguna kami, jadi harus singkat (sebaiknya 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 flag, fitur, atau nama perintah, pengguna mungkin ingin mengetahui informasi selengkapnya.
Gunakan tanda petik terbalik di sekitar kode, simbol, flag, atau kata apa pun yang berisi garis bawah.
Jangan hanya menyalin dan menempel deskripsi bug. Deskripsi bug sering kali tidak jelas dan hanya dapat dipahami oleh kami, sehingga membuat pengguna bingung. Catatan rilis dimaksudkan untuk menjelaskan perubahan yang terjadi dan alasannya dalam bahasa yang dapat dipahami pengguna.
Selalu gunakan bentuk waktu kini 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". Jangan gunakan "is removed" atau "was removed".
Jika Bazel kini melakukan sesuatu secara berbeda, gunakan "X kini $newBehavior, bukan $oldBehavior" dalam bentuk waktu kini. 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 / dihentikan / diubah. Satu kalimat sudah cukup, tetapi kami ingin pengguna dapat mengevaluasi dampak pada build mereka.
JANGAN membuat janji apa pun tentang fungsi mendatang. Hindari "flag ini akan dihapus" atau "hal ini akan diubah". Hal ini akan menimbulkan ketidakpastian. Hal pertama yang akan dipertanyakan pengguna adalah "kapan?", dan kami tidak ingin mereka mulai khawatir tentang build mereka saat ini yang akan rusak pada waktu yang tidak diketahui.
Proses
Sebagai bagian dari proses rilis, kami mengumpulkan tag RELNOTES dari setiap commit. Kami menyalin semuanya ke Google
Dokumen
tempat kami meninjau, mengedit, dan mengatur catatan.
Pengelola rilis mengirim email ke bazel-dev milis. Kontributor Bazel diundang untuk memberikan kontribusi ke dokumen dan memastikan perubahan mereka tercermin dengan benar dalam pengumuman.
Selanjutnya, pengumuman akan dikirimkan ke blog Bazel, menggunakan repositori bazel-blog.