Dari conventional commits ke changelog

Conventional commits memberi changelog tiga hal secara gratis: jenis setiap perubahan, bagian sistem yang tersentuh, dan apakah itu merusak sesuatu. Tidak memberi apa pun lagi. Formulasi, pengelompokan dan seleksi, yang merupakan changelog itu sendiri, tetap sepenuhnya terbuka, dan pipeline yang berpura-pura sebaliknya mengirimkan git log yang diformat.

feat(exports): add CSV column selection
fix(auth): reject expired refresh tokens
chore(deps): bump node-pg to 8.11

Tiga commit dalam format Conventional Commits. Dari ini, mesin bisa memberi tahu Anda bahwa satu adalah fitur, satu perbaikan, satu perawatan, dan bagian sistem mana yang tersentuh masing-masing. Itu sungguh berguna, dan itu seluruh janji konvensi: riwayat commit yang bisa dibaca oleh sesuatu selain manusia. Kesalahannya adalah mengira itu memberi Anda changelog. Itu memberi Anda bahan mentah.

Apa yang ditentukan konvensi?

Jenis, scope opsional, dan deskripsi: type(scope): description. Jenis-jenisnya secara konvensional adalah feat, fix, chore, docs, refactor, test, perf, build, ci. Dua hal menandai breaking change: ! sebelum titik dua, atau footer BREAKING CHANGE:. Alat mengandalkan feat dan fix untuk kenaikan versi minor dan patch, dan penanda breaking untuk major.

Penanda memberi tahu alatnya; tidak memberi tahu pemanggilnya, yang menjadi subjek cara men-deprecate API dan apa itu breaking change. Ini spesifikasi kecil dan layak diikuti bahkan jika Anda tidak pernah menghasilkan apa pun darinya, karena memaksa satu keputusan per commit: apakah ini perubahan yang dilihat pengguna, atau tidak.

Di mana conventional commits berhenti?

Berhenti di kalimat. Semua yang ditangkap konvensi adalah metadata tentang perubahan; perubahan itu sendiri masih dijelaskan dalam kosakata peninjau.

Pesan commit ditulis untuk peninjau. fix(auth): reject expired refresh tokens benar dan tidak memberi tahu apa pun kepada pelanggan. Pembaca changelog ingin “Anda akan diminta login ulang saat sesi benar-benar kedaluwarsa, alih-alih melihat 401 sesekali”.

Scope bersifat internal. exports, auth, ingest adalah nama modul. Stabil, yang membuat mereka baik untuk pengelompokan, dan tidak bermakna bagi siapa pun di luar kode basis.

Satu perubahan sering kali banyak commit. Fitur yang di-merge dalam sebelas commit menghasilkan sebelas entri, sepuluh di antaranya kebisingan, dan meng-squash untuk menyembunyikan itu kehilangan riwayat peninjauan.

chore adalah tempat sampah, bukan kategori. Pembaruan dependensi, perubahan CI dan penggantian nama semuanya jatuh di sana, dan beberapa penting bagi pengguna sementara kebanyakan tidak.

Jadi: konvensi memberi Anda jenis, scope dan status breaking secara gratis, dan membiarkan formulasi, pengelompokan dan seleksi sepenuhnya terbuka. Ketiganya adalah changelog. Siapa sebenarnya pemilik entri changelog membahas siapa yang seharusnya menangani formulasi, pengelompokan, dan seleksi itu, karena konvensinya sendiri tidak punya pendapat soal itu.

Bagaimana changelog dihasilkan dari conventional commits?

Dalam dua lapisan, dan yang kedua harus wajib.

Lapisan satu, otomatis. Saat merge, turunkan entri draf dari commit: jenis dipetakan ke jenis changelog (feat ke Added, fix ke Fixed, penanda breaking ke Changed plus flag), scope disimpan sebagai metadata alih-alih teks, tautan ke PR. Letakkan di bagian Unreleased yang diminta Keep a Changelog.

Lapisan dua, manusia, dan diwajibkan. Sebelum rilis keluar, setiap entri draf mendapat penulisan ulang satu baris dalam kosakata pengguna, atau ditandai internal dan dihapus dari tampilan publik. Ini langkah yang dicoba dilewatkan orang, dan melewatkannya menghasilkan changelog yang terbaca seperti diff.

Detail desain yang penting adalah lapisan dua tidak opsional dalam pipeline. Jika rilis bisa dipotong dengan draf yang tidak diedit, itu akan terjadi, di minggu yang sibuk. Langkah mana yang milik mesin dan mana milik orang adalah seluruh isi otomatisasi changelog.

Memotong rilis juga saat tag git, rilis, dan entri changelog ini bisa selaras atau mulai tidak sinkron; tag git, rilis, dan changelog Anda membahas cara menjaga ketiganya tetap sinkron.

Tiga jebakan

Squash merge memakan footer. Jika platform Anda meng-squash dengan judul PR sebagai pesan, footer BREAKING CHANGE: dari commit di dalam branch itu menghilang, dan alat Anda diam-diam berhenti melihat breaking change. Periksa apa yang sebenarnya disimpan template squash Anda.

Commit revert menghasilkan entri hantu. fix yang di-revert keesokan harinya menghasilkan entri untuk sesuatu yang tidak pernah dirilis, kecuali penurunannya merekonsiliasi revert. Kebanyakan alat tidak melakukan itu.

Kenaikan versi dan changelog jadi tidak sinkron. Jika versi dihitung dari commit dan changelog ditulis manual setelahnya, keduanya menyimpang dalam sekitar dua rilis. Hitung keduanya dalam satu langkah yang sama atau terima salah satunya salah.

Jika Anda ingin bagian mekanisnya tanpa pipeline

Generator changelog kami melakukan langkah penurunan di browser: tempel commit, dapatkan entri yang dikelompokkan dan berjenis. Ini sengaja deterministik dan sepenuhnya sisi klien, jadi commit yang Anda tempel tidak pernah meninggalkan mesin Anda, yang penting saat pesan berasal dari repositori privat. Melakukan separuh pengumpulan dengan jujur dan tidak mencoba lapisan dua, karena lapisan dua adalah penilaian dan alat yang memalsukannya menghasilkan tepatnya changelog yang diperdebatkan artikel ini.

Untuk versi pipeline, alat changelog mencakup apa yang ada.

Ringkasan

Conventional commits menjawab “jenis perubahan apa ini” secara andal dan murah. Tidak menjawab “apa yang harus kita katakan kepada orang-orang”, dan tidak ada jumlah alat di atas pesan commit yang akan melakukannya, karena informasinya tidak pernah ada di pesan commit. Anggarkan untuk penulisan ulang.

FAQ

Apakah conventional commits menghasilkan changelog secara otomatis? Mereka menghasilkan draf secara otomatis: entri berjenis, dengan scope, tertaut. Formulasi untuk pelanggan, pengelompokan dan keputusan apa yang dihilangkan masih membutuhkan seseorang, dan pipeline yang melewatkan langkah itu menerbitkan pesan commit.

Jenis conventional commit mana yang muncul di changelog? feat dan fix selalu, sebagai Added dan Fixed. perf biasanya, sebagai Changed. chore, docs, refactor, test, build dan ci bersifat internal secara default dan hanya muncul jika seseorang mempromosikan salah satunya.

Bagaimana conventional commits menandai breaking change? Sebuah ! setelah jenis atau scope (feat(api)!: ...), atau footer BREAKING CHANGE: di badan commit. Keduanya hilang jika squash merge hanya menyimpan judul PR.

Apakah Anda perlu conventional commits untuk mengotomatisasi changelog? Tidak. Label PR, template PR dan tautan issue membawa metadata yang sama untuk tim yang merge lewat pull request. Conventional commits adalah opsi termurah ketika unit perubahannya adalah commit.

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

Terkait di changeloop: Generator changelog, Perbandingan alat changelog