Belajar Semantic Release - Semantic Release Setup Dasar

#Pendahuluan

Di episode 4 kita memetakan strategi branching: staging untuk release candidate dan main untuk stable. Sekarang saatnya mengubah peta itu menjadi konfigurasi nyata. Semantic-release dikendalikan oleh satu file konfigurasi — release.config.cjs di root repository — yang menentukan branch mana yang dirilis, format tag, dan plugin apa yang dipakai.

Kabar baiknya, kalian tidak perlu menulis plugin dari nol. Semantic-release sudah menyediakan plugin inti yang menangani hampir semua kebutuhan: menganalisis commit, menyusun changelog, mempublikasikan package, membuat tag, dan merilis ke GitHub. Kita tinggal memasang dan merangkainya.

#Pembahasan Utama

#Instalasi

Semantic-release dan plugin inti dipasang sebagai dependency development. Jalankan di root project:

Requirement: Node.js versi 18 ke atas (stabil di 20 atau 22). Plugin @semantic-release/npm opsional — jika proyek kalian bukan package yang dipublish, plugin ini bisa dikonfigurasi agar hanya memperbarui package.json tanpa publish ke registry.

#Konfigurasi Dasar

Semantic-release membaca konfigurasi dari file release.config.cjs atau kunci release di package.json. Berikut contoh lengkap dengan branch main dan staging:

release.config.cjs

module.exports = {
  branches: [
    "main",
    { name: "staging", prerelease: "rc" },
  ],
  tagFormat: "v${version}",
  repositoryUrl: "https://github.com/akun/proyek.git",
  plugins: [
    [
      "@semantic-release/commit-analyzer",
      {
        preset: "conventionalcommits",
        releaseRules: [
          { breaking: true, release: "major" },
          { type: "feat", release: "minor" },
          { type: "fix", release: "patch" },
          { type: "hotfix", release: "patch" },
          { type: "perf", release: "patch" },
          { type: "refactor", release: "patch" },
          { type: "chore", release: "patch" },
          { type: "docs", release: false },
          { type: "test", release: false },
          { type: "ci", release: false },
        ],
      },
    ],
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/git",
    "@semantic-release/github",
  ],
};

Mari bedah bagian-bagian pentingnya:

branches: daftar branch yang boleh rilis. "main" menghasilkan SemVer penuh; object staging dengan prerelease: "rc" menghasilkan 1.2.0-rc.N.
tagFormat: template tag rilis. Nilai v diikuti versi adalah konvensi umum.
releaseRules: aturan pemetaan type commit ke release type. Aturan dievaluasi berurutan; kecocokan pertama yang menang.
Plugin string: plugin yang tidak butuh opsi ditulis sebagai string.

#Custom Rules Commit Analyzer

Bagian releaseRules adalah otak pemetaan. Beberapa pola yang perlu diperhatikan:

{ breaking: true, release: "major" } — apapun type-nya, commit bertanda breaking menaikkan major.
{ type: "feat", release: "minor" } — fitur baru menaikkan minor.
{ type: "fix", release: "patch" } — perbaikan bug menaikkan patch.
{ type: "docs", release: false } — dokumentasi tidak memicu rilis sama sekali.
Aturan yang lebih spesifik menang karena dievaluasi berurutan — tulis breaking change di posisi teratas.

Warning

Hati-hati dengan release: false pada type yang kalian nilai penting. Commit ci, docs, atau test yang memicu rilis hanya akan menaikkan versi tanpa manfaat bagi user — dan membanjiri changelog dengan noise.

#Alternatif: Konfigurasi di package.json

Jika kalian lebih suka satu file lebih sedikit, konfigurasi bisa ditaruh di kunci release pada package.json:

Alternatif: kunci release di package.json

{
  "release": {
    "branches": ["main", { "name": "staging", "prerelease": "rc" }],
    "tagFormat": "v${version}"
  }
}

Kelebihannya: semua konfigurasi project dalam satu file. Kekurangannya: file package.json bisa menjadi besar dan padat, terutama saat releaseRules berjumlah banyak. Untuk proyek dengan aturan yang kompleks, file release.config.cjs terpisah lebih mudah dibaca dan di-review.

#Verifikasi dengan Dry Run

Sebelum menjalankan rilis sungguhan, pastikan konfigurasi berjalan seperti harapan:

Verifikasi konfigurasi tanpa efek samping

npx semantic-release --dry-run --no-ci

--dry-run membuat semantic-release menghitung versi dan changelog tanpa membuat tag, commit, atau publish.
--no-ci melewati pemeriksaan environment CI — berguna saat dijalankan di mesin lokal.

Tip

Di mesin lokal, jangan lupa menambahkan --no-ci. Tanpa flag itu, semantic-release menolak berjalan di luar CI dan langsung keluar dengan pesan "This command can only be run in a CI environment".

Perhatikan output untuk tiga hal: versi yang dihitung, changelog yang dihasilkan, dan cabang yang dirilis. Jika semuanya sesuai harapan, konfigurasi siap diserahkan ke GitHub Actions — yang akan kita bangun di episode 6.

#Penutup

Pada episode 5 ini kalian telah:

Memasang semantic-release dan lima plugin inti via npm.
Menyusun release.config.cjs dengan branch main dan staging rc.
Mengatur releaseRules untuk memetakan type commit ke release type.
Melihat alternatif konfigurasi lewat kunci release di package.json.
Memverifikasi konfigurasi dengan --dry-run --no-ci.

Di episode 6 kita akan menjalankan konfigurasi ini di GitHub Actions: menyiapkan trigger push dan pull request, memisahkan job ci dan release, serta mengelola secret seperti GITHUB_TOKEN dan NPM_TOKEN. Sampai jumpa di episode 6!