Dokumen ini ditargetkan untuk kontributor Bazel.
Deskripsi commit di Bazel menyertakan tag RELNOTES: yang diikuti dengan catatan
rilis. Hal ini digunakan oleh tim Bazel untuk melacak perubahan pada 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 tersebut menambahkan / menghapus / mengubah Bazel dengan cara yang terlihat oleh pengguna, maka mungkin akan menguntungkan untuk menyebutkannya.
Jika perubahannya signifikan, ikuti kebijakan dokumen desain terlebih dahulu.
Panduan
Catatan rilis akan dibaca oleh pengguna kami, sehingga harus singkat (idealnya satu kalimat), hindari jargon (terminologi internal Bazel), harus fokus pada apa saja perubahan tersebut.
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 banyak tentang hal itu.
Gunakan tanda kutip terbalik di sekitar kode, simbol, tanda, atau kata apa pun yang berisi garis bawah.
Jangan hanya menyalin dan menempelkan deskripsi bug. Pertanyaan ini sering kali samar dan hanya masuk akal bagi kita dan membuat pengguna menggaruk-garuk kepala. Catatan rilis dimaksudkan untuk menjelaskan apa yang telah berubah dan alasannya dalam bahasa yang dapat dipahami pengguna.
Selalu gunakan present tense dan format "Bazel now mendukung Y" atau "X sekarang mendukung Z". Kita tidak ingin catatan rilis terdengar seperti entri {i>bug<i}. Semua entri catatan rilis harus informatif dan menggunakan gaya serta bahasa yang konsisten.
Jika ada hal yang tidak digunakan lagi atau dihapus, gunakan "X has been deprecated" atau "X has been removed". Bukan "dihapus" atau "telah dihapus".
Jika Bazel sekarang melakukan sesuatu yang berbeda, gunakan "X now $newBehavior bukan $oldBehavior" dalam present tense. Hal ini memungkinkan pengguna mengetahui secara mendetail apa yang diharapkan saat menggunakan rilis baru.
Jika Bazel sekarang mendukung atau tidak lagi mendukung sesuatu, gunakan "Bazel sekarang 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 buat janji apa pun tentang fungsi di masa mendatang. Hindari "tanda 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 khawatir build mereka saat ini rusak pada waktu yang tidak diketahui.
Proses
Sebagai bagian dari proses
rilis,
kami mengumpulkan tag RELNOTES dari setiap commit. Kami menyalin semuanya di Dokumen
Google
tempat kami meninjau, mengedit, dan mengatur catatan.
Pengelola rilis mengirimkan 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.