Ketika API internal mulai mengirimkan field yang hilang pada respons order, tim backend tidak bisa hanya menebak penyebabnya. Git history menjadi senjata utama untuk menjawab pertanyaan "kapan perubahan terakhir kali bekerja" dan menemukan commit yang menyebabkan regresi.

Artikel ini menyajikan studi kasus nyata: mulai dari gejala awal, langkah reproduksi yang konkret, proses menelusuri riwayat commit, hingga perbaikan teknis dan verifikasi. Fokus utamanya adalah menjaga riwayat git tetap bisa diandalkan saat debugging regresi API.

1. Gejala regresi dan langkah reproduksi

Gejala pertama datang dari tim integrasi yang menjalankan suite QA otomatis: endpoint GET /api/v1/orders/:id tiba-tiba tidak menyertakan field payment_status lagi dalam payload, padahal klien menunggu field tersebut untuk menentukan langkah pemrosesan selanjutnya.

Untuk mereproduksi, pengembang melakukan langkah berikut:

  1. Menyiapkan lingkungan staging yang men-deploy commit terakhir dari branch main.
  2. Menggunakan token API dengan hak akses lengkap.
  3. Memanggil endpoint yang sama dan membandingkan respons dengan JSON baseline yang tersimpan.
  4. Menggunakan curl dan parser JSON untuk memastikan field payment_status hilang secara konsisten, bukan karena caching.

Gejala yang jelas (field hilang, tidak error 500) menunjukkan bahwa logika pengambilan data masih jalan, tapi data yang dikembalikan sudah berubah. Itu adalah kasus klasik regresi yang perlu dipetakan ke riwayat commit.

2. Mengeksplorasi Git history untuk menemukan regresi

Tim memakai pendekatan git history sebagaimana dijelaskan di panduan Lalit: utamakan riwayat linear dan nama commit yang deskriptif agar penelusuran cepat.

2.1 Menyaring commit relevan

Mulai dengan melihat daftar commit terakhir yang menyentuh controller dan serializer order:

git log --oneline --stat -- path/to/order_controller.rb path/to/order_serializer.rb

Dari output ini ditemukan commit 3f2b9a4 yang terlihat menambahkan decorator pada payload.

2.2 Menggunakan git bisect untuk mempercepat root cause

Dikarenakan rentang commit cukup panjang, digunakan git bisect untuk mengecilkan scope:

git bisect start HEAD bad_commit_hash good_commit_hash git bisect run ./tests/check-order-payload.sh

Script pengecekan di atas memanggil API lokal dan mengecek keberadaan payment_status. Dalam dua iterasi bisect, ditemukan commit 3f2b9a4 sebagai titik perubahan.

Analisis diff menunjukkan bahwa serializer sekarang memfilter field berdasarkan policy baru, tapi payment_status tidak ditambahkan ke daftar field yang diizinkan ketika policy yang lama disederhanakan.

3. Perbaikan teknis dan verifikasi

Setelah identifikasi, langkah perbaikan terdiri dari:

  • Memperbarui definisi OrderPolicy#allowed_attributes agar selalu mencakup payment_status.
  • Menambahkan tes integrasi serialisasi yang memanggil serializer dengan peran berbeda untuk memastikan field tidak hilang.

Contoh perubahan:

def allowed_attributes(user_role)
  base = %i[id total status payment_status]
  base += %i[internal_notes] if user_role.admin?
  base
end

Perubahan ini menjaga agar field tersertakan secara eksplisit, bukan bergantung pada atribut default.

Verifikasi dilakukan dengan:

  • Unit test serializer memastikan payment_status selalu diserialisasi.
  • Script reproduksi manual (curl) memeriksa payload staging.
  • Pipeline CI menjalankan regression test suite yang sebelumnya gagal.

Setelah perbaikan, tim menutup bisect dan menandai commit baru dengan deskripsi yang menyebutkan payment_status.

4. Pelajaran menjaga riwayat git berguna saat debugging

Beberapa pelajaran konkret:

  • Commit kecil dengan pesan spesifik: Pesan seperti "tweak payload policy" tidak membantu; lebih baik "menambahkan payment_status ke policy serializer".
  • Jaga riwayat linier pada release branch: Rebase topic branch sebelum merge membuat git log lebih mudah dipindai.
  • Tambahkan regression test bersama commit funzional: Menyertakan tes otomatis membantu git bisect ketika menentukan commit buruk.
  • Dokumentasikan alasan perubahan policy: Catatan mengapa field ditambahkan mempercepat penelusuran ketika field tersebut hilang di masa depan.

Penerapan prinsip ini memperkuat nilai Git history sebagai alat debugging. Dengan riwayat yang bersih dan tes yang bisa dijalankan otomatis, menemukan regresi API lebih cepat dan pemicunya lebih transparan.