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 dokumen desain kebijakan 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 setiap catatan rilis harus berisi link. Jika deskripsi menyebutkan penanda, fitur, nama perintah, pengguna mungkin ingin tahu lebih banyak tentang hal itu.
Gunakan tanda kutip terbalik di sekitar kode, simbol, penanda, 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 membiarkan pengguna menggaruk-garuk kepalanya. Catatan rilis dimaksudkan untuk menjelaskan apa yang telah berubah dan mengapa dalam bahasa yang dapat dipahami pengguna.
Selalu gunakan {i>present tense<i} dan format "Bazel sekarang mendukung Y" atau "X sekarang melakukan 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 adalah tetapi kita ingin pengguna dapat mengevaluasi dampaknya 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 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 rilis
proses ini,
kita mengumpulkan tag RELNOTES dari setiap commit. Kami menyalin semuanya di Google
Dokumen
tempat kami meninjau, mengedit, dan mengatur catatan.
Pengelola rilis mengirimkan email ke bazel-dev. Kontributor Bazel diundang untuk berkontribusi pada dokumen dan memastikan perubahan mereka tercermin dengan benar dalam pengumuman.
Nanti, pengumuman akan dikirimkan ke Bazel blog, menggunakan bazel-blog repositori yang baru.