Dokumen ini ditujukan untuk kontributor Bazel.
Deskripsi commit di Bazel menyertakan tag RELNOTES: yang diikuti dengan rilis
catatan. Server ini digunakan oleh tim Bazel untuk
melacak perubahan pada setiap rilis dan
pengumuman rilis.
Ringkasan
Apakah perubahan Anda merupakan perbaikan bug? Dalam hal ini, Anda tidak memerlukan catatan rilis. Memohon menyertakan referensi ke masalah GitHub.
Jika perubahan menambahkan / menghapus / mengubah Bazel dengan cara yang terlihat oleh pengguna, maka mungkin akan menguntungkan jika Anda menyebutkannya.
Jika perubahannya signifikan, ikuti kebijakan dokumen desain terlebih dahulu.
Panduan
Catatan rilis akan dibaca oleh pengguna, jadi catatannya harus singkat (idealnya satu kalimat), hindari jargon (istilah internal Bazel-Bazel), harus fokus pada apa perubahan tersebut.
Sertakan link ke dokumentasi yang relevan. Hampir semua catatan rilis harus berisi link. Jika deskripsi menyebutkan penanda, fitur, nama perintah, pengguna mungkin ingin tahu lebih banyak tentang hal itu.
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 kita terdengar seperti entri {i>bug<i}. Semua rilis entri catatan harus informatif dan menggunakan gaya dan bahasa yang konsisten.
Jika ada konten yang tidak digunakan lagi atau dihapus, gunakan "X has been deprecated" atau "X telah dihapus". Tidak "dihapus" atau "telah dihapus."
Jika Bazel sekarang melakukan sesuatu dengan cara berbeda, gunakan "X now $newBehavior, bukan $oldBehavior" dalam bentuk masa kini. Hal ini memungkinkan pengguna mengetahui secara rinci apa yang harus saat mereka menggunakan rilis baru.
Jika Bazel sekarang mendukung atau tidak lagi mendukung sesuatu, gunakan "Bazel sekarang mendukung / tidak lagi mendukung X".
Jelaskan alasan konten 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 "flag ini akan dihapus" atau "ini akan diubah." Hal ini menimbulkan ketidakpastian. Hal pertama pengguna akan bertanya-tanya adalah "kapan?" dan kita tidak ingin mereka mulai mengkhawatirkan 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 Google
Dokumen
tempat kami 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.
Kemudian, pengumuman akan dikirim ke blog Bazel, menggunakan repositori bazel-blog.