Release notes GitHub: buat otomatis, lalu rapikan isinya

Release notes GitHub adalah deskripsi yang melekat pada sebuah rilis di halaman Releases repositori, dan GitHub bisa menulis draf pertamanya untuk Anda dari pull request yang di-merge sejak tag sebelumnya. Drafnya berupa daftar judul pull request yang dikelompokkan menurut label, ditambah baris kontributor dan tautan compare. Draf itu akurat, lengkap, dan ditulis untuk orang yang me-merge pull request tersebut. Mengubahnya menjadi sesuatu yang bisa dibaca pengguna proyek butuh satu berkas .github/release.yml dan tahap edit singkat; keduanya dijelaskan di bawah.

Bagaimana cara membuat release notes otomatis di GitHub?

Buka formulir rilis, pilih atau buat tag, lalu klik “Generate release notes”. GitHub mencari tag rilis sebelumnya, mendaftar setiap pull request yang di-merge ke branch target di antara keduanya, dan menulis satu baris per pull request berisi judul, penulis, dan nomornya. Dari baris perintah, gh release create <tag> --generate-notes melakukan hal yang sama dan menerbitkan rilisnya dalam satu langkah; --notes-start-tag menentukan dari tag lama mana rentangnya dimulai.

Fitur ini bekerja dari pull request, jadi repositori yang me-merge langsung ke main tanpa pull request mendapat draf kosong. Squash merge tidak masalah, karena pull request-nya tetap ada. Merge commit dari branch berumur panjang ke main menghasilkan satu baris untuk pull request yang me-merge, tanpa satu pun pull request yang sebelumnya di-merge ke branch itu. Jika rentangnya terlihat salah, penyebab umumnya adalah tag sebelumnya hilang atau urutannya keliru; generator memakai rilis terbaru di branch target, dan tag tanpa rilis yang melekat padanya diabaikan.

Halaman GitHub Docs tentang release notes yang dibuat otomatis membahas tombolnya, dan manual gh release create membahas flag CLI-nya.

Apa yang diubah release.yml?

.github/release.yml memberi tahu generator pull request mana yang harus dikeluarkan dan bagaimana mengelompokkan sisanya. Tanpa berkas ini, semua pull request masuk ke satu daftar, termasuk Dependabot. Dengan berkas ini, pull request disortir ke kategori berdasarkan label, dan kebisingan berlabel atau buatan bot menghilang.

# .github/release.yml
changelog:
  exclude:
    labels:
      - skip-changelog
    authors:
      - dependabot
      - renovate
  categories:
    - title: Breaking changes
      labels:
        - breaking-change
    - title: New
      labels:
        - enhancement
    - title: Fixed
      labels:
        - bug
    - title: Other changes
      labels:
        - "*"

Tiga aturan yang perlu diketahui. Kategori dicocokkan berurutan, jadi pull request dengan label breaking-change sekaligus bug masuk ke judul pertama yang cocok. Penangkap-semua "*" wajib ada jika Anda ingin pull request tanpa label muncul sama sekali; tanpanya, pull request itu dibuang diam-diam. Dan berkas ini hanya memengaruhi apa yang ditulis generator, jadi mengubahnya tidak menyentuh catatan yang sudah ada. Tim yang sudah memberi label pull request untuk pemeriksaan changelog di CI bisa memakai ulang label yang sama di sini.

Mengapa release notes GitHub hasil generator terbaca buruk?

Karena judul pull request ditulis untuk peninjau, sebelum perubahannya selesai, dan menggambarkan kodenya. “Refactor export worker to use streaming” adalah judul pull request yang bagus dan release note yang tidak berguna, karena orang yang membaca rilis ingin tahu bahwa ekspor di atas 100 MB tidak lagi time out.

Alasan kedua, setiap pull request yang di-merge mendapat bobot yang sama. Perbaikan typo satu baris duduk bersebelahan dengan alur autentikasi baru, dalam urutan apa pun mereka di-merge. Pembaca harus memindai seluruh daftar untuk menemukan tiga baris yang memengaruhi mereka.

Alasan ketiga, draf itu tidak punya pembuka. Daftar empat puluh baris tanpa satu kalimat di atasnya tidak memberi tahu siapa pun apakah rilis ini aman diambil, butuh migrasi, atau hanya ada untuk mengunci sebuah dependensi.

Apa yang harus diubah pada tahap edit?

Pertahankan daftar yang dihasilkan dan tambahkan ke atasnya, alih-alih menulis ulang dari nol. Daftar itu adalah jejak audit; nomor pull request adalah cara seseorang menelusuri satu baris kembali ke diff-nya. Tahap edit menambahkan bagian yang tidak bisa diketahui generator.

1. Tulis dua atau tiga kalimat di bagian atas. Untuk apa rilis ini, apakah upgrade butuh tindakan, dan apa yang harus dibaca lebih dulu. Jika ada breaking change, sebutkan di baris pertama.
2. Tulis ulang baris-baris yang akan dipedulikan orang dari sisi pembaca: gejala yang hilang, hal yang kini bisa mereka lakukan, pengaturan yang berpindah. Biarkan nomor pull request di ujung baris. Cara menulis release notes berisi bentuk lengkapnya; release notes perbaikan bug membahas khusus baris perbaikan.
3. Pindahkan apa pun yang harus dilakukan pembaca ke bagiannya sendiri, dengan perintah atau pengaturan yang persis. Breaking change yang terkubur di daftar “Other changes” adalah tiket dukungan seminggu kemudian.
4. Jangan hapus apa pun dari daftar yang dihasilkan. Lipat di bawah judul “Full list of changes” jika panjang, tapi pertahankan, karena kontributor proyek sendiri memakainya.

Dengan cara ini, release notes GitHub butuh sekitar sepuluh menit untuk diedit pada rilis biasa, dan catatannya melayani dua audiens: ringkasan di atas untuk pengguna, daftar di bawah untuk kontributor.

Haruskah rilis GitHub menjadi changelog Anda?

Hanya jika semua orang yang perlu tahu tentang sebuah perubahan sudah membaca halaman Releases. Untuk library yang dipakai developer lewat package manager, itu sering benar, dan halaman Releases plus CHANGELOG.md di repositori sudah cukup. Untuk produk dengan pengguna yang tidak pernah membuka GitHub, tidak: halaman rilis ditulis di tingkat yang salah, berada di balik URL untuk developer, dan tidak bisa di-subscribe oleh orang tanpa akun GitHub.

Pola yang bertahan adalah memperlakukan rilis GitHub sebagai catatan untuk developer dan changelog produk sebagai catatan untuk pembaca, dengan rilis yang menautkan ke entri changelog. Tag git, rilis, dan changelog membahas bagaimana ketiga catatan itu saling sejajar. Jika changelog produk dihasilkan dari commit yang sama, generator changelog memberi draf untuk sisi itu juga, dan pembagian changelog vs release notes menjelaskan detail mana yang masuk ke mana.

Bagaimana cara memversikan release notes itu sendiri?

Rilis yang sudah diterbitkan di GitHub bisa diedit kapan saja, dan editannya tidak meninggalkan riwayat yang terlihat di halaman. Untuk kebanyakan proyek itu tidak masalah. Untuk proyek yang catatannya menjadi rekaman yang diandalkan kepatuhan atau pelanggan, dua kebiasaan membantu: simpan teks kanonisnya di repositori (CHANGELOG.md, atau folder docs/releases/) dan buat badan rilis menunjuk ke sana, lalu aktifkan immutable releases di repositori jika paket Anda menyediakannya, yang mengunci tag dan aset begitu diterbitkan. GitHub Docs tentang mengelola rilis menjelaskan draf, pre-release, dan label “latest”, yang ditetapkan menurut urutan versi semantik kecuali Anda mengaturnya sendiri.

FAQ

Bisakah release notes GitHub dibuat otomatis? Bisa. Tombol “Generate release notes” di formulir rilis, flag --generate-notes pada gh release create, dan endpoint REST generate-notes semuanya menghasilkan draf dari pull request yang di-merge sejak tag rilis sebelumnya. Berkas .github/release.yml mengatur pengelompokan dan pengecualiannya.

Mengapa release notes hasil generator saya kosong? Generator mendaftar pull request, jadi commit langsung ke branch tidak muncul, dan rentangnya dimulai dari rilis terbaru di branch target, bukan tag terbaru. Pastikan rilis sebelumnya ada dan perubahannya masuk lewat pull request.

Apakah release.yml berlaku untuk rilis yang sudah ada? Tidak. Berkas itu hanya membentuk catatan yang dibuat setelah berkasnya ada. Badan rilis yang sudah ada tetap seperti semula sampai seseorang mengeditnya.

Sebaiknya pakai release notes GitHub atau CHANGELOG.md? Keduanya, jika proyek punya kontributor dan pengguna. Halaman rilis adalah tempat developer mencari dan tempat aset berada; berkas di repositori bertahan jika proyek pindah dari GitHub dan bisa dibaca offline. Buat release notes-nya, jaga berkasnya tetap mutakhir, dan tautkan keduanya.

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, Dokumentasi developer