Siapa yang menulis changelog, dan siapa yang seharusnya

Tanyakan pada tim siapa yang menulis changelog dan jawaban jujurnya biasanya “siapa pun yang ingat”, yang merupakan mode kegagalan yang sama yang coba diperbaiki mewajibkan entri changelog di CI di tingkat mekanis. Tapi memaksa entri ada tidak memutuskan siapa yang memenuhi syarat untuk menulis yang baik, dan tim yang melewati pertanyaan itu cenderung default ke siapa pun yang paling mudah diwajibkan, biasanya penulis PR, tanpa memeriksa apakah itu benar-benar orang yang bisa menulisnya dengan baik.

Mengapa penulis PR tidak otomatis menjadi penulis changelog terbaik?

Karena dia tahu implementasinya, belum tentu dampaknya, dan itu jenis pengetahuan yang berbeda. Di mana conventional commits berhenti membahas kesenjangan ini dari sisi pesan commit: fix(auth): reject expired refresh tokens benar dan tidak memberi tahu apa pun kepada pelanggan, dan orang yang menulis perbaikan itu sering kali orang yang paling tidak siap menerjemahkannya, karena dia sudah berpikir dalam istilah bug itu selama berjam-jam dan kehilangan pandangan luar tentang apa yang sebenarnya dialami pengguna. Ini alasan yang sama mengapa penulis teknis ada sebagai profesi: menerjemahkan implementasi menjadi dampak adalah keterampilan tersendiri, berbeda dari membangun sesuatu itu sendiri, dan itu butuh latihan tak peduli seberapa bagus developer itu dalam kodenya sendiri.

Apakah itu berarti produk atau dukungan seharusnya menulis setiap entri sebagai gantinya?

Tidak, karena mereka punya kesenjangan yang berlawanan: mereka tahu apa yang penting bagi pengguna tapi tidak selalu tahu apa yang sebenarnya dirilis, yang menghasilkan entri yang mudah dibaca tapi kadang salah dalam cakupan, klaim “sekarang mendukung X” untuk fitur yang masih di belakang flag, atau perbaikan yang digambarkan lengkap padahal hanya mencakup satu dari tiga kasus. Mode kegagalan entri yang ditulis developer adalah sulit-dibaca-tapi-akurat; mode kegagalan entri yang ditulis PM adalah mudah-dibaca-tapi-belum-terverifikasi. Tidak ada peran yang memiliki kedua paruh dari apa yang dibutuhkan entri yang baik.

Seperti apa sebenarnya model kepemilikan yang berhasil?

Draf dari siapa pun yang paling dekat dengan perubahan, ditinjau oleh siapa pun yang paling dekat dengan pengguna, dengan satu orang bernama bertanggung jawab atas kata-kata akhir alih-alih semua orang berasumsi orang lain akan menangkap masalah. Draf itu perlu ada dan akurat lebih daripada perlu bagus; kalimat kasar yang ditulis developer yang dengan benar mengatakan apa yang berubah adalah titik awal yang lebih baik daripada yang dipoles tapi belum diverifikasi, karena menulis ulang untuk kejelasan lebih mudah daripada menulis ulang untuk kebenaran. Langkah tinjauan adalah di mana PM atau pemimpin dukungan membaca draf dan mengajukan satu pertanyaan yang menangkap kesenjangan keterbacaan: apakah saya akan memahami ini jika saya tidak melihat kodenya.

Haruskah orang yang sama selalu menjadi yang bertanggung jawab, atau bergilir?

Bernama dan stabil mengalahkan bergilir, setidaknya untuk persetujuan akhir. Pemilik bergilir berarti setiap entri ditinjau oleh seseorang yang menurunkan ulang konvensi tim dari awal, yang persis bagaimana suaranya melenceng dari entri ke entri dan pembaca mulai menyadari changelog ditulis oleh komite. Satu orang, atau kelompok stabil yang sangat kecil, mengumpulkan penilaian dari waktu ke waktu, kapan mengatakan “ditingkatkan” versus menyebutkan angka spesifik, kapan perbaikan butuh entrinya sendiri versus dilipat ke dalam batch, dan penilaian itu lebih berharga daripada mendistribusikan pekerjaan secara merata.

Draf (developer, dari PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Ditinjau (pemilik changelog, diperiksa terhadap PR nyata):
"Diperbaiki: ekspor yang diurutkan berdasarkan tanggal
bisa mengembalikan hasil di luar urutan melewati halaman
pertama. Sekarang konsisten di semua halaman."

Apakah tim kecil butuh proses sebanyak ini untuk satu baris teks?

Bukan peran sebagai orang terpisah, tapi dua langkahnya masih penting bahkan sendirian. Tim satu orang adalah baik developer maupun peninjau, dan disiplin yang bertahan di skala itu adalah melakukan tinjauan sebagai langkah mental terpisah, bukan langsung melompat dari menulis perbaikan ke menerbitkan deskripsinya dalam satu tarikan napas. Jebakan di skala kecil adalah melewatkan langkah kedua sepenuhnya, bukan kurangnya orang kedua, karena tidak ada yang eksternal memaksanya, dan kesenjangan akurasi yang ada untuk ditangkap langkah itu tidak hilang hanya karena orang yang sama secara teoretis bisa menyadari titik butanya sendiri.

Apa yang terjadi ketika tidak ada yang bertanggung jawab atas entri akhir?

Changelog memburuk secara tidak merata alih-alih gagal secara terbuka, yang lebih buruk karena tidak ada yang menyadarinya sampai pembaca menunjukkannya. Beberapa entri tetap tajam karena siapa pun yang menulisnya peduli; yang lain menjadi samar, “berbagai peningkatan dan perbaikan bug”, karena siapa pun yang menulisnya bergerak cepat dan tidak ada yang menangkapnya sebelum diterbitkan. Batasan format Keep a Changelog menangkap penyimpangan struktural, tanggal yang hilang, kategori yang salah, tapi tidak ada dalam template yang menangkap entri samar yang secara teknis diformat dengan baik, yang persis kesenjangan yang ada untuk ditutup pemilik bernama.

FAQ

Haruskah pemilik changelog berupa peran engineering atau produk? Keduanya bisa berhasil jika orang tersebut punya kelancaran teknis untuk memverifikasi cakupan sekaligus cukup jarak dari implementasi untuk menulis bagi pembaca luar; gelarnya kurang penting daripada apakah dia bisa melakukan kedua paruh, atau tahu kepada siapa harus bertanya untuk paruh yang tidak bisa dia lakukan.

Apakah jadwal bergilir gaya siaga pernah cocok untuk kepemilikan changelog? Untuk volume, kadang, jika tim terlalu kecil bagi satu orang untuk meninjau semuanya; untuk suara dan penilaian, tidak, karena itu persis yang dikikis rotasi. Rotasi yang berbagi beban menulis draf sambil mempertahankan satu peninjau stabil mendapat manfaatnya tanpa penyimpangannya.

Apa tanda tercepat ada yang salah dengan susunan kepemilikan saat ini? Entri yang akurat tapi sulit dibaca, atau mudah dibaca tapi salah dalam cakupan, dalam pola yang mengikuti siapa yang menulisnya. Jika kualitas berkorelasi dengan penulis alih-alih tetap konsisten, kepemilikan adalah kesenjangannya, bukan keterampilan menulis.

Apakah otomasi mengurangi seberapa penting kepemilikan? Itu mengurangi seberapa banyak penulisan yang dibutuhkan, bukan seberapa banyak penilaian yang dibutuhkan. Otomasi changelog membahas apa yang bisa dihasilkan pipeline dengan aman, pemformatan, penerbitan, cross-posting; kata-kata, pengelompokan, dan apa yang dianggap layak disebutkan tetap menjadi keputusan manusia tidak peduli seberapa banyak pipeline yang diotomasi.

Bagaimana jika penulis PR dan peninjau tidak setuju soal kata-katanya? Keputusan peninjau yang menang, karena pertanyaan yang mereka jawab, apakah pembaca luar akan memahami ini, adalah yang menjadi alasan peran itu ada. Itu tidak membuat pandangan developer tidak berharga: jika ketidaksepakatannya soal akurasi alih-alih pemilihan kata, peninjau yang mengalah, karena cakupan adalah bagian yang harus benar dari penulis. Memisahkan dua jenis ketidaksepakatan ini, kata-kata versus akurasi, menghentikan sebagian besar sebelum berubah jadi kebuntuan.

Klaim teknis dalam artikel ini belum ditinjau secara independen. Jika ada yang keliru, beri tahu kami dan kami akan memperbaikinya.

Terkait di changeloop: Perbandingan alat changelog, Generator changelog