Otomatisasi changelog, dan batasannya

Otomatisasi changelog berhasil ketika mengotomatisasi pengumpulan, klasifikasi dan penerbitan, dan berhenti di seleksi dan formulasi. Otomatisasi semuanya dan Anda mengirimkan git log yang diformat; jangan otomatisasi apa pun dan changelog ditulis dalam ledakan, dari ingatan, sebelum rilis. Pertanyaan yang berguna adalah bagian mana yang harus diotomatisasi, bukan seberapa banyak.

Proyek otomatisasi changelog gagal dalam salah satu dari dua arah, dan keduanya bisa diprediksi sejak rapat desain pertama. Otomatisasi terlalu sedikit dan changelog menjadi dokumen yang seharusnya diperbarui seseorang, yang berarti diperbarui dalam ledakan, oleh siapa pun yang kebagian tugas termalang. Otomatisasi terlalu banyak dan berubah menjadi git log yang diformat: lengkap, akurat, dan tidak dibaca siapa pun.

Bagian mana dari changelog yang harus diotomatisasi?

Tiga dari empat langkah. Pengumpulan dan penerbitan sepenuhnya; klasifikasi sebagai langkah pertama dengan penggantian manusia; seleksi dan formulasi tidak pernah.

Pengumpulan. Mengeluarkan perubahan dari tempat mereka terjadi (commit, PR, tiket) dan memasukkannya ke daftar. Otomatisasi ini sepenuhnya. Manusia buruk dalam hal ini, membosankan, dan merupakan langkah yang dilewati saat tenggat waktu. Conventional commits atau label PR biasanya bahan mentahnya.

Klasifikasi. Memutuskan apakah sesuatu itu Added, Fixed, Changed, Deprecated, Removed atau Security. Otomatisasi langkah pertama dari jenis commit atau label PR, dan biarkan manusia menggantinya. Akurasi di sini sekitar delapan puluh persen hanya dari metadata, dan dua puluh persen yang salah terkonsentrasi tepat di entri yang penting, karena ambiguitas berkorelasi dengan pentingnya.

Seleksi dan formulasi. Memutuskan apa yang harus diketahui pembaca dan bagaimana menyampaikannya. Jangan otomatisasi ini. Ini seluruh nilai dari artefak. Semua yang lain adalah logistik.

Penerbitan. Membawa entri yang selesai ke halaman, feed, email, widget in-app, kanal Slack. Otomatisasi sepenuhnya, dan dari satu sumber. Ini tempat sebagian besar upaya manual sebenarnya dihabiskan, dan hampir tidak ada yang menghitungnya. Ini juga langkah yang bisa memberi tahu orang yang meminta perubahan bahwa itu sudah dirilis, yang merupakan seluruh isi dari menutup lingkaran umpan balik dari sisi changelog. Separuh email dari langkah itu punya bentuknya sendiri, di template email update produk.

Poin terakhir itu layak dipikirkan. Tim cenderung melihat changelog sebagai masalah penulisan, lalu menghabiskan sebagian besar waktu pada distribusi: menyalin entri ke alat email, memformat ulang untuk in-app, menempel ke Slack, memperbarui halaman dokumen. Menulis butuh satu jam. Menyalin butuh satu jam setiap rilis, selamanya, dan itu bagian yang seharusnya dimiliki mesin.

Apa yang terjadi ketika batasnya bergeser?

Geser ke atas dan Anda dapat dump git. Otomatisasi penuh dari commit menghasilkan bump deps, fix flaky test, wip dan address review comments di depan pelanggan. Setiap tim yang melakukan ini kemudian menambahkan filter, dan filter tersebut adalah langkah seleksi yang diperkenalkan kembali dengan nama lain, dengan ergonomi yang lebih buruk.

Geser ke bawah dan Anda dapat ledakan. Pengumpulan sepenuhnya manual berarti entri ditulis dari ingatan saat rilis. Itu mode yang diperingatkan Keep a Changelog sejak awal, dan memburuk diam-diam: changelog terlihat terpelihara sampai tepat minggu ketika tidak ada yang punya waktu.

Seperti apa pipeline otomatisasi changelog?

Empat langkah, dengan tepat satu gerbang manusia, diletakkan di tempat draf menjadi publik.

1. Saat merge, turunkan entri draf dari PR: jenis dari label atau prefiks commit, judul sebagai draf pertama, tautan kembali ke PR, penulis tercatat. Letakkan di bak yang belum dirilis.
2. Siapa pun bisa mengedit draf apa pun kapan saja, dan mengedit itu murah. Kebanyakan mendapat satu baris ditulis ulang.
3. Memotong rilis mengharuskan setiap entri di bak sudah diedit atau ditandai secara eksplisit sebagai internal. Gerbang ini adalah seluruh desainnya. Tanpanya, draf dirilis tanpa disunting di minggu yang sibuk.
4. Menerbitkan adalah fan-out dari set yang dirilis: halaman publik, feed, email, widget, posting Slack. Satu sumber, beberapa rendering, tidak ada penyalinan.

Langkah 3 satu-satunya tempat yang membutuhkan seseorang, dan butuh sekitar sepuluh menit per rilis begitu draf-nya layak. Di mana permintaan pelanggan terlibat, draf juga membawa issue yang ditutupnya, yang memungkinkan langkah 4 memberi tahu peminta; template permintaan fitur dirancang agar tautan itu bertahan. Posisi langkah ini dalam alur rilis yang lebih luas adalah topik proses manajemen rilis.

Apa yang dibutuhkan otomatisasi dari data Anda?

Tidak ada yang di atas berfungsi jika changelog adalah berkas Markdown, karena berkas tidak bisa dirender ke lima permukaan tanpa diurai ulang, dan mengurai prosa adalah cara Anda berakhir dengan widget yang menampilkan setengah judul.

Entri perlu terstruktur: jenis, tanggal, versi atau pengenal rilis, audiens, badan dan tautan. Lalu berkas, halaman, feed dan email semuanya adalah tampilan. Poin struktural itu satu-satunya hal yang layak dibenarkan sebelum memilih alat, karena itu yang tidak bisa Anda tambahkan dengan murah setelahnya. Tidak ada satu pun dari itu berfungsi selama entri tidak benar-benar dibuat untuk setiap perubahan yang membutuhkannya; mewajibkan entri changelog di CI membahas cara membuat pipeline menolak merge tanpa entri, alih-alih menyerahkan langkah itu pada ingatan.

Kami membangun changeloop, di mana changelog dulu adalah feed baru kemudian halaman, jadi bacalah itu sebagai kepentingan alih-alih rekomendasi netral; harga adalah satu repositori gratis tanpa kartu, cukup untuk melihat bentuknya. Alat changelog adalah rangkuman kami tentang apa lagi yang ada, termasuk produk yang kami saingi, dan generator changelog melakukan langkah pengumpulan dan klasifikasi di browser jika Anda ingin melihat penurunannya sebelum berkomitmen pada pipeline.

Tesnya

Hitung menit antara perubahan yang di-merge dan perubahan itu terlihat bagi pelanggan yang tidak membaca repo Anda. Jika sebagian besar menit itu adalah seseorang menyalin teks antar alat, otomatisasi yang Anda butuhkan ada di penerbitan, bukan penulisan.

FAQ

Bisakah AI menulis changelog? Bisa menyusun draf. Model yang diberi pull request yang di-merge kebanyakan menghasilkan draf pertama judul dan badan yang bisa digunakan, yang merupakan langkah pengumpulan dan klasifikasi yang dilakukan lebih baik. Seleksi, apakah pembaca harus diberi tahu sama sekali, dan formulasi akhir, masih membutuhkan orang yang tahu audiensnya, dan pipeline yang menerbitkan draf tanpa gerbang itu telah mengotomatisasi langkah yang salah.

Apa bedanya generator changelog dengan otomatisasi changelog? Generator mengubah commit menjadi daftar yang diformat sekali, sesuai permintaan. Otomatisasi berjalan di setiap merge, memelihara bak yang belum dirilis, mensyaratkan tinjauan manusia untuk rilis, dan menerbitkan ke setiap permukaan dari satu sumber. Generator adalah langkah pertama pipeline, dijalankan secara manual.

Haruskah changelog diotomatisasi dari commit atau dari pull request? Dari pull request, di mana unit perubahannya adalah PR: judul dan deskripsi ditulis sekali, untuk seluruh perubahan, dan PR menautkan issue yang ditutupnya. Penurunan berbasis commit berhasil ketika commit adalah unitnya dan mengikuti konvensi.

Bagaimana cara mencegah otomatisasi menerbitkan perubahan internal? Klasifikasikan chore, ci, test, refactor dan pembaruan dependensi sebagai internal secara default, dan jadikan promosi ke publik tindakan yang disengaja. Default yang terbalik, publik kecuali seseorang menyembunyikannya, adalah cara bump deps sampai ke pelanggan.

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