[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.
📋 Daftar Isi
- Pengenalan
- Format Versi
- Aturan Kenaikan Versi
- Pre-release dan Build Metadata
- Perbandingan Versi
- Contoh Penggunaan
- Best Practices
- Tools & Integrasi
- Keuntungan
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
| Bagian | Deskripsi |
|---|---|
| MAJOR | Perubahan yang tidak backward compatible |
| MINOR | Fitur baru yang backward compatible |
| PATCH | Perbaikan 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 awal0.2.0: fitur baru atau perubahan yang mungkin tidak kompatibel0.2.1: perbaikan bug pada seri0.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:
| Commit | Dampak 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. ✨