Versioning

Versioning #

Role yang digunakan di banyak proyek adalah aset yang perlu dikelola dengan hati-hati. Tanpa versioning yang baik, update role yang tampaknya kecil bisa membreak deployment di proyek yang menggunakannya tanpa peringatan. Sebaliknya, tanpa mekanisme untuk mengelola versi, proyek yang berbeda akan menggunakan versi role yang berbeda dan tidak sinkron. Artikel ini membahas cara mengelola lifecycle role dengan versioning yang tepat.

Mengapa Versioning Role Penting #

Bayangkan skenario ini: tim infrastruktur memperbarui role nginx untuk menambahkan fitur baru — mereka mengubah nama variabel nginx_port menjadi nginx_http_port untuk konsistensi. Tanpa versioning, semua proyek yang menggunakan role ini dan menjalankan ansible-galaxy install akan mendapatkan versi terbaru — dan semua playbook yang masih menggunakan nginx_port akan gagal.

Tanpa versioning:
  Proyek A menggunakan nginx role (versi "terbaru")
  Proyek B menggunakan nginx role (versi "terbaru")
  → Update role mengganti nama variabel
  → Proyek A dan B langsung break tanpa peringatan

Dengan versioning:
  Proyek A pin ke nginx role v1.2.0
  Proyek B pin ke nginx role v1.2.0
  → Update role dirilis sebagai v2.0.0
  → Proyek A dan B tetap berjalan normal
  → Update ke v2.0.0 dilakukan secara terkontrol, satu proyek sekaligus

Semantic Versioning untuk Role #

Gunakan semantic versioning (SemVer) untuk role: MAJOR.MINOR.PATCH

MAJOR — breaking change: perubahan yang membutuhkan update di playbook pengguna
        Contoh: nama variabel berubah, direktori berubah, OS yang tidak lagi didukung

MINOR — fitur baru yang backward-compatible
        Contoh: tambah dukungan untuk distro baru, tambah variabel opsional baru

PATCH — bug fix yang backward-compatible
        Contoh: perbaiki bug di template, perbaiki kondisi yang salah

v1.0.0  → Rilis pertama yang stabil
v1.0.1  → Perbaiki bug di template SSL
v1.1.0  → Tambah dukungan untuk Ubuntu 24.04
v2.0.0  → Ganti nama variabel untuk konsistensi (BREAKING CHANGE)

Git Tags sebagai Versi #

Cara paling praktis untuk mem-versioning role yang disimpan di Git adalah menggunakan Git tags:

# Setelah melakukan perubahan dan commit
git add .
git commit -m "feat: tambah dukungan Ubuntu 24.04"

# Beri tag sesuai versi
git tag -a v1.1.0 -m "Release v1.1.0 — tambah dukungan Ubuntu 24.04"
git push origin v1.1.0

# Untuk breaking change
git tag -a v2.0.0 -m "Release v2.0.0 — rename nginx_port ke nginx_http_port (BREAKING)"
git push origin v2.0.0

Pin Versi di requirements.yml #

Setiap proyek yang menggunakan role eksternal harus pin versi di requirements.yml:

# requirements.yml
---
roles:
  # BENAR: pin ke versi spesifik
  - name: nginx
    src: https://github.com/company/ansible-role-nginx.git
    scm: git
    version: "v1.2.0"    # ← Pin ke versi spesifik

  - name: postgresql
    src: https://github.com/company/ansible-role-postgresql.git
    scm: git
    version: "v2.1.3"

  # ANTI-PATTERN: tanpa pin versi
  - name: common
    src: https://github.com/company/ansible-role-common.git
    # version tidak di-set = selalu ambil versi terbaru = berbahaya

# Install role dengan versi yang dipinned
ansible-galaxy install -r requirements.yml --roles-path roles/

# Cek role yang terinstal
ansible-galaxy list

CHANGELOG: Komunikasi Perubahan #

Setiap role yang digunakan bersama harus punya file CHANGELOG.md yang mendokumentasikan perubahan di setiap versi:

# CHANGELOG

## [2.0.0] - 2024-03-15

### BREAKING CHANGES
- Rename variabel `nginx_port` → `nginx_http_port` untuk konsistensi
- Hapus dukungan untuk Ubuntu 18.04 (sudah EOL)

### Migrasi dari v1.x ke v2.x
1. Ganti semua penggunaan `nginx_port` menjadi `nginx_http_port` di:
   - group_vars/
   - host_vars/
   - playbook vars
2. Jika masih menggunakan Ubuntu 18.04, upgrade OS terlebih dahulu

## [1.2.0] - 2024-02-01

### Added
- Tambah dukungan untuk Ubuntu 24.04
- Tambah variabel `nginx_access_log_format` untuk kustomisasi format log

### Fixed
- Perbaiki bug di template SSL yang menghasilkan konfigurasi tidak valid

## [1.1.0] - 2024-01-15

### Added
- Tambah variabel `nginx_ssl_protocols` untuk mengontrol protocol TLS yang diizinkan

Workflow Upgrade yang Aman #

Saat ada versi baru role yang ingin digunakan, ikuti proses ini:

1. Baca CHANGELOG — pahami apa yang berubah
        │
2. Cek apakah ada breaking change
        │
        ├── Tidak ada breaking change (MINOR/PATCH)
        │       → Update requirements.yml
        │       → Test di staging
        │       → Deploy ke production jika staging berhasil
        │
        └── Ada breaking change (MAJOR)
                → Buat branch baru di proyek
                → Update requirements.yml ke versi baru
                → Update group_vars/host_vars sesuai perubahan
                → Test intensif di staging
                → Deploy ke production dengan rollback plan yang siap

Ringkasan #

  • Semantic versioning untuk role: MAJOR (breaking change), MINOR (fitur baru backward-compatible), PATCH (bug fix).
  • Gunakan Git tags untuk mem-versioning role — mudah di-reference dan bisa di-checkout kapan saja.
  • Selalu pin versi di requirements.yml — tanpa pin, update role bisa membreak proyek tanpa peringatan.
  • CHANGELOG.md wajib ada untuk role yang digunakan bersama — dokumentasikan semua perubahan, terutama breaking changes dan panduan migrasi.
  • Upgrade ke MAJOR version membutuhkan proses yang lebih hati-hati — branch terpisah, update variabel, test intensif, dan rollback plan.
  • Jangan pernah menggunakan version: main atau tanpa version di production — hanya untuk development.

← Sebelumnya: Parameterized   Berikutnya: User & Permission →

About | Author | Content Scope | Editorial Policy | Privacy Policy | Disclaimer | Contact