Belajar Semantic Release - Audit, Changelog & Release Notes

#Pendahuluan

Di episode 13 kita menutup gerbang dengan branch protection. Sekarang bayangkan: rilis 1.4.0 sudah terbit, lalu muncul bug. Tim QA bertanya "apa saja yang berubah di versi ini?" Jika jawabannya harus diingat dari kepala, kalian sedang menabung utang dokumentasi.

Episode ini membahas audit changelog & release notes: bagaimana release-notes-generator mengubah commit history menjadi changelog terstruktur, bagaimana plugin changelog menulis CHANGELOG.md ke repository, dan bagaimana release notes itu otomatis tayang di GitHub Releases.

#Peran release-notes-generator

@semantic-release/release-notes-generator adalah plugin inti yang membaca semua commit sejak tag terakhir, lalu mengelompokkannya:

Features — dari commit feat.
Bug Fixes — dari commit fix.
Performance Improvements — dari perf.
BREAKING CHANGES — bagian khusus untuk perubahan yang memutus kompatibilitas.
Kelompok lain seperti docs, chore, dan test biasanya disembunyikan secara default.

Outputnya berupa teks release notes yang kemudian dipakai oleh plugin lain — menjadi isi CHANGELOG.md oleh @semantic-release/changelog, dan menjadi body GitHub Release oleh @semantic-release/github.

#Setup Changelog Otomatis

Dua plugin tambahan dibutuhkan agar changelog benar-benar tertulis di repository: @semantic-release/changelog (menulis file) dan @semantic-release/git (meng-commit file tersebut). Instal keduanya:

Install plugin changelog dan git

bun add -D @semantic-release/changelog @semantic-release/git

Kemudian daftarkan keduanya di release.config.cjs, tepat setelah release-notes-generator:

release.config.cjs dengan changelog & git

module.exports = {
  branches: ['main'],
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    ['@semantic-release/changelog', {
      changelogFile: 'CHANGELOG.md',
    }],
    '@semantic-release/npm',
    ['@semantic-release/git', {
      assets: ['CHANGELOG.md', 'package.json'],
      message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
    }],
    '@semantic-release/github',
  ],
};

Urutan di dalam array menentukan urutan eksekusi pada fase yang sama. Plugin npm meng-update package.json dengan versi baru pada fase prepare, dan plugin git yang diletakkan setelahnya meng-commit CHANGELOG.md bersama package.json dalam satu commit rilis.

Tip

Pesan commit otomatis chore(release): 1.4.0 [skip ci] memakai kata kunci skip-ci agar commit hasil release tidak memicu workflow, tidak memicu release baru, dan tetap lolos aturan commitlint. Ini pola yang aman dan lazim dipakai di banyak tim.

#Contoh Output Changelog

Contoh CHANGELOG.md yang dihasilkan otomatis

# [1.4.0](https://github.com/devnull/learn-semantic-release/compare/v1.3.1...v1.4.0) (2026-08-03)
 
### Features
 
* **api:** tambahkan endpoint export laporan ([#88](https://github.com/devnull/learn-semantic-release/issues/88)) ([a1b2c3d](https://github.com/devnull/learn-semantic-release/commit/a1b2c3d))
* **auth:** dukung login dengan passkey ([#90](https://github.com/devnull/learn-semantic-release/issues/90)) ([e4f5a6b](https://github.com/devnull/learn-semantic-release/commit/e4f5a6b))
 
### Bug Fixes
 
* **export:** perbaiki kolom tanggal kosong pada CSV ([#87](https://github.com/devnull/learn-semantic-release/issues/87)) ([c7d8e9f](https://github.com/devnull/learn-semantic-release/commit/c7d8e9f))
* **ui:** perbaiki overlap tombol di layar kecil ([#91](https://github.com/devnull/learn-semantic-release/issues/91)) ([b0a1b2c](https://github.com/devnull/learn-semantic-release/commit/b0a1b2c))

Perhatikan beberapa hal penting dari output di atas:

Judul menampilkan perbandingan versi: compare/v1.3.1...v1.4.0 — tautan diff otomatis.
Setiap entri menyertakan nomor isu #88 dan hash commit, keduanya tertaut ke GitHub.
Kelompok Features dan Bug Fixes dihasilkan semata-mata dari tipe commit feat dan fix.
Tanggal rilis ditulis otomatis.

#Menghubungkan Release Notes ke GitHub Releases

@semantic-release/github mengambil output generateNotes dan menjadikannya body GitHub Release. Artinya changelog, GitHub Release, dan tag v1.4.0 selalu konsisten karena semuanya lahir dari satu sumber yang sama.

Tautan ke isu dan PR muncul karena release-notes-generator menerjemahkan pola #N pada subject commit menjadi referensi isu. Contoh: subject fix(export): perbaiki kolom tanggal kosong (#87) otomatis terhubung ke isu #87 di release notes. Ini yang membuat release bisa diaudit — QA tinggal klik isu yang dirujuk tanpa membuka git log.

Untuk melampirkan artifact seperti binary atau installer ke release, tambahkan assets pada konfigurasi github:

Melampirkan artifact ke GitHub Release

['@semantic-release/github', {
  assets: [
    { path: 'dist/app-linux-x64.zip', label: 'Installer Linux' },
    { path: 'dist/app-macos-arm64.zip', label: 'Installer macOS' },
  ],
}],

#Menulis Changelog yang Jelas

Kualitas changelog bergantung pada kualitas commit message. Beberapa kebiasaan yang membuat changelog lebih berbicara:

Tulis subject commit sebagai kalimat aktif yang menjawab "apa yang berubah": fix(checkout): perbaiki error total harga nol.
Jangan menaruh detail teknis berlebihan di subject; rincian bisa masuk ke body commit.
Rujuk isu atau PR terkait dengan #N agar tautan muncul otomatis.
Gunakan footer BREAKING CHANGE: dengan penjelasan migrasi agar bagian breaking changes dalam changelog jelas.

Tip

Jangan pernah menulis CHANGELOG.md dengan tangan setelah release otomatis aktif — perubahan manual akan tertimpa pada rilis berikutnya. Jadikan changelog sebagai produk turunan, bukan dokumen yang dikelola manual. Jika ingin menambahkan konteks ekstra, tulis di GitHub Release notes alih-alih mengedit file.

#Penutup

Rekap episode 14:

release-notes-generator mengubah commit history menjadi release notes terstruktur.
@semantic-release/changelog menulis CHANGELOG.md, @semantic-release/git meng-commit-nya.
@semantic-release/github menautkan release notes ke GitHub Releases lengkap dengan diff dan isu.
Kualitas changelog = kualitas commit message: aktif, ringkas, dan merujuk isu.
Changelog adalah produk turunan; jangan dikelola manual.

Setiap versi kini punya jejak audit yang lengkap. Di episode 15 kita memperluas strategi ini ke Multi-branch Release Strategy — mendukung branch rc dan main secara bersamaan, memahami perbedaan prerelease, release candidate, dan stable release, serta aturan prioritas SemVer untuk -rc.N. Sampai jumpa!