Dokumen ini ditujukan untuk kontributor Bazel.
Deskripsi commit di Bazel menyertakan tag RELNOTES: yang diikuti dengan catatan
rilis. API 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 untuk masalah GitHub.
Jika perubahan menambahkan / menghapus / mengubah Bazel secara jelas dan terlihat oleh pengguna, mungkin akan bermanfaat jika Anda menyebutkannya.
Jika perubahannya signifikan, ikuti kebijakan dokumen desain terlebih dahulu.
Panduan
Catatan rilis akan dibaca oleh pengguna, sehingga harus singkat (idealnya satu kalimat), hindari jargon (terminologi internal Bazel), harus fokus pada tujuan perubahan.
Sertakan link ke dokumentasi yang relevan. Hampir setiap catatan rilis harus berisi link. Jika deskripsi menyebutkan flag, fitur, atau nama perintah, pengguna mungkin ingin mengetahui lebih banyak tentangnya.
Gunakan tanda kutip di sekitar kode, simbol, tanda, atau kata apa pun yang berisi garis bawah.
Jangan hanya menyalin dan menempelkan deskripsi bug. Mereka sering kali samar dan hanya masuk akal bagi kita dan membuat pengguna menggaruk-garuk kepalanya. Catatan rilis dimaksudkan untuk menjelaskan hal yang telah berubah dan alasannya dalam bahasa yang dapat dipahami pengguna.
Selalu gunakan {i>present tense<i} dan format "Bazel sekarang mendukung Y" atau "X sekarang mendukung Z". Kita tidak ingin catatan rilis kita terdengar seperti entri {i>bug<i}. Semua entri catatan rilis harus informatif dan menggunakan gaya dan bahasa yang konsisten.
Jika ada sesuatu yang tidak digunakan lagi atau dihapus, gunakan "X telah digunakan lagi" atau "X telah dihapus". Bukan "dihapus" atau "dihapus".
Jika Bazel sekarang melakukan sesuatu dengan cara yang berbeda, gunakan "X now $newBehavior, bukan $oldBehavior" dalam bentuk masa kini. Hal ini memberi tahu pengguna secara mendetail hal yang diharapkan 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. Cukup satu kalimat, tetapi kami ingin pengguna dapat mengevaluasi dampak pada build mereka.
JANGAN membuat janji apa pun tentang fungsi di masa mendatang. Hindari "flag ini akan dihapus" atau "ini akan diubah". Hal ini menimbulkan ketidakpastian. Hal pertama yang akan membuat pengguna bertanya-tanya 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 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.
Nantinya, pengumuman akan dikirimkan ke blog Bazel, menggunakan repositori bazel-blog.