Back to Blogs

[ID] Semantic Versioning

VersioningReleaseGit
Lazuardi Akbar Imani 2026-10-05
[ID] Semantic Versioning

Semantic Versioning

Panduan lengkap tentang Semantic Versioning (SemVer) — standar untuk memberi nomor versi secara konsisten berdasarkan perubahan pada public API sebuah software.

© Dezkrazzer

📋 Daftar Isi

Pengenalan

Semantic Versioning adalah konvensi penomoran versi yang membuat arti sebuah perubahan dapat dipahami hanya dari nomor versinya. SemVer sangat berguna untuk:

  • Menyampaikan apakah sebuah rilis berisi breaking changes
  • Membantu pengguna memilih versi yang kompatibel
  • Mengurangi risiko upgrade yang tidak terduga
  • Mengotomatisasi release, changelog, dan dependency management

Artikel ini mengikuti spesifikasi Semantic Versioning 2.0.0.

Format Versi

Format dasar Semantic Versioning adalah:

MAJOR.MINOR.PATCH

Contoh:

2.4.1

Penjelasan

BagianDeskripsi
MAJORPerubahan yang tidak backward compatible
MINORFitur baru yang backward compatible
PATCHPerbaikan bug yang backward compatible

Versi valid harus berupa tiga angka non-negatif tanpa awalan v dalam metadata versi. Dalam praktiknya, tag Git sering ditulis dengan awalan v, misalnya v2.4.1.

Aturan Kenaikan Versi

MAJOR

Naikkan angka MAJOR ketika public API berubah dan pengguna perlu menyesuaikan kode mereka.

1.8.3 → 2.0.0

Contoh:

  • Menghapus function atau endpoint publik
  • Mengubah nama atau tipe parameter
  • Mengubah format response yang digunakan pengguna
  • Mengubah perilaku yang sebelumnya dijamin oleh API

MINOR

Naikkan angka MINOR ketika menambahkan kemampuan baru tanpa merusak API yang sudah ada. PATCH di-reset menjadi 0.

1.8.3 → 1.9.0

Contoh:

  • Menambahkan endpoint baru
  • Menambahkan optional parameter
  • Menambahkan fitur baru yang tidak mengubah perilaku lama
  • Menambahkan dukungan terhadap platform baru

PATCH

Naikkan angka PATCH ketika memperbaiki bug yang tidak mengubah public API.

1.8.3 → 1.8.4

Contoh:

  • Memperbaiki validasi input
  • Memperbaiki error handling
  • Memperbaiki security bug tanpa mengubah kontrak API
  • Meningkatkan performa tanpa mengubah hasil yang diharapkan

Versi Awal 0.y.z

Versi 0.y.z menandakan software masih dalam tahap awal pengembangan. Public API belum dianggap stabil.

  • 0.1.0: rilis fitur awal
  • 0.2.0: fitur baru atau perubahan yang mungkin tidak kompatibel
  • 0.2.1: perbaikan bug pada seri 0.2.x

Sebelum versi 1.0.0, setiap MINOR dapat berisi perubahan yang breaking. Tetap dokumentasikan perubahan tersebut dengan jelas.

Versi 1.0.0

Gunakan 1.0.0 ketika public API sudah stabil dan software siap digunakan secara resmi. Setelah itu, ikuti aturan MAJOR, MINOR, dan PATCH secara konsisten.

Pre-release dan Build Metadata

Pre-release

Pre-release ditulis setelah tanda hubung (-). Versi ini belum dianggap siap sebagai rilis stabil.

2.0.0-alpha
2.0.0-alpha.1
2.0.0-beta.2
2.0.0-rc.1

Urutan umum:

alpha → beta → rc → release

Pre-release memiliki prioritas lebih rendah daripada versi stabil:

2.0.0-alpha < 2.0.0-rc.1 < 2.0.0

Identifier pre-release hanya boleh berisi karakter ASCII alfanumerik dan tanda hubung. Identifier numerik tidak boleh memiliki awalan nol.

Build Metadata

Build metadata ditulis setelah tanda tambah (+) dan tidak memengaruhi prioritas versi.

2.0.0+20261005
2.0.0+commit.a1b2c3d

2.0.0+build.1 dan 2.0.0+build.2 memiliki prioritas yang sama. Gunakan metadata untuk informasi build, commit, atau pipeline.

Perbandingan Versi

Versi dibandingkan dari kiri ke kanan: MAJOR, kemudian MINOR, lalu PATCH.

1.10.0 > 1.9.9

Jangan membandingkan nomor versi sebagai teks biasa. Secara numerik, 10 lebih besar daripada 9.

Contoh prioritas:

1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0

Contoh Penggunaan

1. Rilis Patch

Versi saat ini: 1.4.2
Perubahan: memperbaiki crash saat file kosong di-upload
Versi berikutnya: 1.4.3

2. Rilis Minor

Versi saat ini: 1.4.3
Perubahan: menambahkan endpoint pencarian baru tanpa mengubah endpoint lama
Versi berikutnya: 1.5.0

3. Rilis Major

Versi saat ini: 1.5.0
Perubahan: mengganti response `user` menjadi `account`
Versi berikutnya: 2.0.0

4. Rilis Pre-release

npm version 2.0.0-beta.1
npm version 2.0.0-rc.1
npm version 2.0.0

5. Git Tag

git tag -a v2.0.0 -m "release: v2.0.0"
git push origin v2.0.0

Best Practices

✅ Lakukan

  • Dokumentasikan public API dan perubahan yang memengaruhi pengguna
  • Naikkan hanya satu level utama untuk setiap rilis: MAJOR, MINOR, atau PATCH
  • Reset angka di sebelah kanan saat menaikkan MAJOR atau MINOR
  • Gunakan pre-release untuk menguji versi yang belum stabil
  • Gunakan changelog untuk menjelaskan perubahan di setiap versi
  • Sertakan migration guide untuk setiap breaking change
  • Sinkronkan versi package, Git tag, dan release notes
  • Gunakan semantic commit untuk membantu menentukan level versi secara otomatis

❌ Jangan Lakukan

# ❌ Salah: menambah fitur baru tetapi hanya menaikkan PATCH
1.4.2 → 1.4.3

# ❌ Salah: memperbaiki bug tetapi langsung menaikkan MAJOR
1.4.2 → 2.0.0

# ❌ Salah: menggunakan angka dengan awalan nol
01.04.002

# ❌ Salah: menganggap build metadata mengubah prioritas
2.0.0+build.1 > 2.0.0+build.2

Hubungan dengan Semantic Commit

Semantic Commit Message dapat dipetakan ke kenaikan versi:

CommitDampak versi
fix:PATCH
feat:MINOR
feat!: atau footer BREAKING CHANGE:MAJOR
docs:, test:, chore:Biasanya tidak membuat rilis

Mapping ini harus disesuaikan dengan kebijakan proyek. Perubahan refactor, perf, atau build dapat menjadi MAJOR jika mengubah kontrak publik.

Tools & Integrasi

npm

npm version patch
npm version minor
npm version major

Perintah tersebut memperbarui versi package, membuat commit, dan membuat Git tag sesuai konfigurasi npm.

semantic-release

semantic-release dapat menentukan versi berikutnya berdasarkan semantic commit:

npm install --save-dev semantic-release
npx semantic-release

Dengan konfigurasi CI yang benar, tool ini dapat membuat release note, Git tag, dan mempublikasikan package secara otomatis.

Changesets

Changesets menyimpan niat rilis secara eksplisit sebelum perubahan digabungkan:

npm install --save-dev @changesets/cli
npx changeset
npx changeset version
npx changeset publish

GitHub Releases

Gunakan Git tag seperti v1.5.0 untuk membuat GitHub Release. Sertakan:

  • Ringkasan fitur dan perbaikan
  • Daftar breaking changes
  • Instruksi migrasi
  • Link ke dokumentasi terkait

Keuntungan

🔍 Perubahan Lebih Mudah Dipahami

Nomor versi langsung memberi sinyal risiko upgrade kepada pengguna.

🛡️ Upgrade Lebih Aman

Pengguna dapat memilih untuk menerima PATCH dan MINOR secara otomatis, sementara MAJOR ditinjau secara manual.

📦 Dependency Management Lebih Terprediksi

Package manager dapat menggunakan version range untuk mengambil versi yang kompatibel.

🤖 Release Otomatis

Semantic Versioning yang dipadukan dengan semantic commit membantu mengotomatisasi changelog, Git tag, dan publikasi package.

📝 Riwayat Rilis Lebih Rapi

Setiap versi memiliki arti dan alasan yang jelas, sehingga proses rollback dan troubleshooting menjadi lebih mudah.

Referensi


Dibuat untuk membantu tim memahami dan menerapkan Semantic Versioning secara konsisten. ✨