Dokumen ini ditargetkan pada kontributor Bazel.
Deskripsi commit di Bazel mencakup tag RELNOTES:, diikuti dengan catatan
rilis. Kode ini digunakan oleh tim Bazel untuk melacak perubahan pada setiap rilis dan
menulis pengumuman rilis.
Ringkasan
Apakah perubahan Anda adalah 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, mungkin sebaiknya Anda menyebutnya.
Jika perubahannya signifikan, ikuti kebijakan dokumen desain terlebih dahulu.
Panduan
Catatan rilis akan dibaca oleh pengguna kami, sehingga harus singkat (idealnya satu kalimat), menghindari jargon (istilah terminologi Bazel internal), harus fokus pada hal perubahannya.
Sertakan link ke dokumentasi yang relevan. Hampir semua catatan rilis harus berisi link. Jika deskripsi menyebutkan flag, fitur, nama perintah, pengguna mungkin ingin mengetahuinya lebih lanjut.
Gunakan tanda kutip belakang pada kode, simbol, tanda, atau kata apa pun yang berisi garis bawah.
Jangan hanya menyalin dan menempelkan deskripsi bug. Gambar ini sering kali samar dan hanya masuk akal bagi kami dan membuat pengguna menggaruk kepalanya. Catatan rilis dimaksudkan untuk menjelaskan apa saja yang berubah dan mengapa dalam bahasa yang dapat dipahami pengguna.
Selalu gunakan present tense dan format "Bazel kini mendukung Y" atau "X sekarang mendukung Z". Kita tidak ingin catatan rilis kita terdengar seperti entri bug. Semua entri catatan rilis harus informatif dan menggunakan gaya serta bahasa yang konsisten.
Jika sesuatu tidak digunakan lagi atau dihapus, gunakan "X sudah tidak digunakan lagi" atau "X telah dihapus". Tidak "dihapus" atau "dihapus".
Jika sekarang Bazel melakukan sesuatu yang berbeda, gunakan "X now $newBehavior, bukan $oldBehavior" dalam bentuk masa kini. Hal ini memungkinkan pengguna mengetahui secara detail apa yang akan diharapkan saat menggunakan rilis baru.
Jika Bazel sekarang mendukung atau tidak lagi mendukung sesuatu, gunakan "Bazel sekarang mendukung / tidak lagi mendukung X".
Jelaskan mengapa sesuatu telah dihapus / tidak digunakan lagi / diubah. Satu kalimat sudah cukup, tetapi kita ingin pengguna dapat mengevaluasi dampaknya pada build.
JANGAN buat janji 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 pengguna mulai mengkhawatirkan build saat ini yang rusak pada waktu yang tidak diketahui.
Memproses
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 perubahannya ditampilkan dengan benar dalam pengumuman.
Nantinya, pengumuman akan dikirim ke blog Bazel, menggunakan repositori bazel-blog.