20. Conventional Commits

Conventional Commits adalah spesifikasi ringan untuk pesan commit Git yang memberikan seperangkat aturan eksplisit untuk membuat riwayat commit yang terstruktur dan mudah dibaca oleh manusia maupun mesin.

Penerapan standar ini sangat krusial bagi tim Frontend Bit Group Asia untuk mendukung otomatisasi perilisan (seperti auto-generation CHANGELOG) dan penentuan versi rilis secara otomatis berdasarkan aturan Semantic Versioning (SemVer).

A. Struktur Utama Pesan Commit

Setiap pesan commit wajib mengikuti format terstruktur berikut:

<tipe>[ruang-lingkup opsional]: <deskripsi singkat>

[badan/deskripsi detail opsional]

[footer opsional]

Komponen Utama:

1. Header (Baris Pertama):
   • <tipe>: Menjelaskan maksud dari perubahan (wajib).
   • [ruang-lingkup opsional]: Menjelaskan bagian kode/modul yang diubah (ditulis dalam tanda kurung, e.g., (auth), (checkout)).
   • <deskripsi singkat>: Penjelasan singkat dalam bentuk kalimat perintah (imperative mood), tidak diawali dengan huruf kapital, dan tidak diakhiri tanda titik.
2. Badan / Body (Kosongkan 1 baris setelah header):
   • Penjelasan detail mengenai motivasi perubahan dan perbedaannya dengan kode sebelumnya.
3. Footer (Kosongkan 1 baris setelah body):
   • Informasi seperti referensi tiket (Jira/GitHub Issues) atau deklarasi perubahan merusak (breaking changes).

B. Jenis-Jenis Tipe Commit (Commit Types)

Gunakan tipe commit yang sesuai dari daftar standar di bawah ini:

C. Deklarasi Perubahan Merusak (Breaking Changes)

Breaking Changes mengindikasikan adanya perubahan yang tidak kompatibel dengan versi sebelumnya (backward-incompatible). Ini akan memicu kenaikan versi MAJOR di SemVer.

Ada dua cara untuk mendeklarasikan Breaking Changes:

1. Menggunakan Tanda Seru (!) di Header: Diletakkan langsung setelah tipe atau sebelum tanda titik dua (:).

   • Contoh: feat(api)!: remove support for deprecated v1 endpoints

2. Mencantumkan BREAKING CHANGE: pada Footer: Diikuti dengan penjelasan detail mengenai apa yang rusak dan alternatif solusinya.

   feat(auth): switch from local session to JWT tokens
   
   BREAKING CHANGE: local session storage is no longer supported.
   All client requests must now include the Bearer token in headers.
   

D. Contoh-Contoh Penerapan

Berikut adalah contoh pesan commit yang baik dan terstandarisasi:

1. Commit Sederhana (Hanya Header)

fix(ui): resolve overlap on dashboard sidebar

Penjelasan: Perbaikan visual pada sidebar dashboard. Singkat, langsung pada intinya, menggunakan huruf kecil semua di deskripsi.

2. Commit dengan Detail & Tiket Jira (Jira Integration)

feat(checkout): implement credit card checkout payment method

Added Stripe integration for handling payment processing.
Supported card brands: Visa, Mastercard, and JCB.

Closes BIT-421

Penjelasan: Menambahkan fitur checkout kartu kredit, menyertakan deskripsi perubahan di badan commit, dan mereferensikan/menutup tiket Jira/GitHub dengan ID BIT-421.

3. Commit dengan Breaking Change (Major Release)

refactor(theme)!: drop support for legacy theme structure

Theme configuration now uses a centralized configuration file in json format.

BREAKING CHANGE: the previous CSS variables in root are no longer read.
Developers must migrate their customization settings to `theme.config.json`.

Penjelasan: Melakukan refaktor besar-besaran yang merusak kompatibilitas tema lama. Menggunakan ! setelah refactor(theme) dan memberikan informasi detail di footer.

E. Mengapa Tim Kita Menggunakan Conventional Commits?

1. Penyusunan CHANGELOG Otomatis: Menggunakan alat bantu seperti standard-version atau semantic-release, sistem dapat secara otomatis menyaring riwayat Git dan memilah fitur (feat) serta perbaikan (fix) untuk menghasilkan file CHANGELOG.md terbaru tanpa intervensi manual.

2. Penentuan Versi Rilis yang Akurat (Semantic Versioning):

   • Jika ada commit dengan BREAKING CHANGE atau ! ➔ Naik versi MAJOR (e.g., 1.0.0 ➔ 2.0.0).
   • Jika hanya ada commit feat ➔ Naik versi MINOR (e.g., 1.0.0 ➔ 1.1.0).
   • Jika hanya ada commit fix ➔ Naik versi PATCH (e.g., 1.0.0 ➔ 1.0.1).

3. Membantu Proses Code Review: Reviewer dapat memahami maksud dari setiap commit secara sekilas hanya dengan membaca judul/header commit-nya saja.

4. Navigasi Riwayat Git yang Efisien: Melacak perubahan tertentu di masa lalu menjadi jauh lebih cepat dengan menggunakan pencarian berbasis tipe, contohnya: git log --grep="feat(auth)".

F. Penegakan Aturan (Enforcement)

Untuk memastikan semua developer mematuhi aturan ini, kita memasang tool otomatis yang bertindak sebagai gatekeeper sebelum commit berhasil dibuat:

1. Husky: Dipakai untuk mengaktifkan Git Hooks lokal secara otomatis di komputer developer.
2. Commitlint: Memvalidasi teks pesan commit berdasarkan aturan Conventional Commits ketika developer menjalankan perintah git commit.

[!WARNING] Jika pesan commit Anda tidak sesuai format (misalnya: git commit -m "benerin bug login"), maka transaksi commit akan ditolak otomatis oleh linter dan Anda harus mengulangi commit dengan format yang benar.