Dokumen ini ditujukan untuk kontributor Bazel.
Deskripsi commit di Bazel menyertakan tag RELNOTES:, diikuti dengan catatan
rilis. Ini digunakan oleh tim Bazel untuk melacak perubahan dalam setiap rilis dan menulis
pengumuman rilis.
Ringkasan
Apakah perubahan Anda merupakan 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, sebaiknya sebutkan perubahan tersebut.
Jika perubahannya signifikan, ikuti kebijakan dokumen desain terlebih dahulu.
Panduan
Catatan rilis akan dibaca oleh pengguna kami, jadi harus singkat (idealnya satu kalimat), hindari jargon (terminologi internal Bazel), harus berfokus pada isi perubahan.
Sertakan link ke dokumentasi yang relevan. Hampir semua catatan rilis harus berisi link. Jika deskripsi menyebutkan flag, fitur, nama perintah, pengguna mungkin ingin mengetahui lebih lanjut tentangnya.
Gunakan tanda petik terbalik di sekitar kode, simbol, flag, atau kata apa pun yang berisi garis bawah.
Jangan hanya menyalin dan menempelkan deskripsi bug. Sering kali, error ini bersifat samar dan hanya membuat kita mengerti, sementara pengguna tidak. Catatan rilis dimaksudkan untuk menjelaskan apa yang telah berubah dan alasannya dalam bahasa yang dapat dipahami pengguna.
Selalu gunakan bentuk kata kerja sekarang dan format "Bazel kini mendukung Y" atau "X kini mendukung Z". Kita tidak ingin catatan rilis terdengar seperti entri bug. Semua entri catatan rilis harus informatif dan menggunakan gaya dan bahasa yang konsisten.
Jika sesuatu tidak digunakan lagi atau dihapus, gunakan "X tidak digunakan lagi" atau "X telah dihapus". Bukan "dihapus" atau "telah dihapus".
Jika Bazel sekarang melakukan sesuatu secara berbeda, gunakan "X sekarang $newBehavior, bukan $oldBehavior" dalam bentuk present tense. Hal ini memungkinkan pengguna mengetahui secara mendetail apa yang akan mereka temukan saat menggunakan rilis baru.
Jika Bazel sekarang mendukung atau tidak lagi mendukung sesuatu, gunakan "Bazel now supports / no longer supports X".
Jelaskan alasan sesuatu telah dihapus / tidak digunakan lagi / diubah. Satu kalimat sudah cukup, tetapi kita ingin pengguna dapat mengevaluasi dampaknya pada build mereka.
JANGAN membuat janji apa pun tentang fungsi pada masa mendatang. Hindari "tanda ini akan dihapus" atau "ini akan diubah". Hal ini menimbulkan ketidakpastian. Hal pertama yang akan ditanyakan pengguna adalah "kapan?" dan kami tidak ingin mereka mulai khawatir build saat ini rusak pada waktu yang tidak diketahui.
Proses
Sebagai bagian dari proses
rilis,
kami mengumpulkan tag RELNOTES dari setiap commit. Kita menyalin semuanya ke Google Dokumen 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 ditampilkan dengan benar dalam pengumuman.
Kemudian, pengumuman akan dikirim ke blog Bazel, menggunakan repositori bazel-blog.