Release Document #
Ketika terjadi production incident, pertanyaan pertama yang muncul biasanya adalah: “Apa yang berubah sejak kemarin?” Jika tidak ada yang bisa menjawab dengan pasti — karena tidak ada catatan yang terstruktur — maka debugging akan berlangsung lebih lama dari yang seharusnya. Release document per sprint hadir untuk menjawab pertanyaan itu sebelum pertanyaan itu sempat menimbulkan kepanikan. Ini bukan sekadar catatan rilis — ini adalah single source of truth yang menjelaskan apa yang berubah, di mana, mengapa, dan apa yang harus dilakukan jika sesuatu berjalan tidak sesuai rencana.
Apa Itu Release Document? #
Release document per sprint adalah dokumen yang dibuat setiap akhir sprint — atau tepat sebelum deployment ke environment tertentu — yang merangkum semua perubahan yang dikirim dalam sprint tersebut. Ia bukan changelog teknikal yang di-generate otomatis dari commit log, dan bukan laporan sprint untuk manajemen. Ia berada di antara keduanya: cukup teknikal untuk dipahami engineer, cukup ringkas untuk dibaca PM dan stakeholder.
Dokumen ini mencakup fitur baru, perubahan behavior yang ada, bug fix, perubahan konfigurasi atau infrastruktur, keputusan teknis (RFC), serta risiko dan rencana rollback. Yang paling penting: ia selalu dapat ditelusuri ke task, PR, dan RFC yang relevan — tidak ada perubahan yang tidak bisa diverifikasi asal-usulnya.
flowchart LR
Sprint[Sprint Backlog] --> RD[Release Document]
Board["Sprint Board\nJira / Linear"] --> RD
RFC[RFC terkait] --> RD
PR[Pull Requests] --> RD
RD --> Staging[Deploy Staging]
RD --> Prod[Deploy Production]
RD --> Archive[Arsip Pengetahuan Tim]Mengapa Release Document Penting? #
Mempercepat Incident Response #
Tanpa release document, incident response dimulai dengan pertanyaan yang membuang waktu:
// Skenario tanpa release document
03:15 AM — alert: error rate melonjak 400%
On-call: "Apa yang berubah tadi malam?"
Developer A: "Saya deploy payment fix"
Developer B: "Saya juga deploy config change"
Infra: "Ada juga update dependency di service C"
On-call: "Oke, mana yang menyebabkan ini?"
→ 45 menit dihabiskan untuk investigasi dasar sebelum bisa mulai debugging
// Skenario dengan release document
03:15 AM — alert: error rate melonjak 400%
On-call: buka release document Sprint 42
→ Dalam 2 menit: tahu persis apa yang berubah, di service mana, dan PR mana
→ Langsung bisa memulai debugging yang bermakna
Menghilangkan Ketergantungan pada Ingatan #
Engineer yang melakukan deployment tidak akan selalu tersedia saat incident terjadi. Malam hari, akhir pekan, atau sudah resign. Release document memastikan pengetahuan tentang sebuah rilis tidak hilang bersama orang yang melakukannya.
Mempermudah Traceability #
Dari sebuah bug di production, kita harus bisa menelusuri ke belakang:
flowchart RL
Bug[Bug di Production] --> RD[Release Document Sprint N]
RD --> Task[Task di Sprint Board]
RD --> PR[Pull Request]
RD --> RFC[RFC jika ada]
Task --> AC[Acceptance Criteria]
PR --> Code[Kode yang berubah]
RFC --> Decision[Alasan keputusan teknis]Tanpa rantai traceability ini, setiap investigasi dimulai dari nol.
Mendukung Onboarding Engineer Baru #
Engineer yang baru bergabung bisa membaca release document dari beberapa sprint terakhir untuk memahami: sistem apa saja yang aktif diubah, pola keputusan teknis tim, dan area-area yang sedang dalam transisi.
Komponen Utama Release Document #
Header dan Metadata #
Setiap release document dimulai dengan metadata yang memudahkan pencarian dan referensi di masa depan:
# Release Document — Sprint 42
**Sprint:** Sprint 42
**Tanggal Rilis:** 2026-06-10
**Environment:** Production
**Release Owner:** [nama engineer]
**Sprint Board:** [link ke Jira/Linear/GitHub Projects]
**Status Sprint:** Done (20/20 story selesai)
Header yang konsisten antar sprint membuat dokumen mudah dibandingkan dan dicari. Gunakan format tanggal yang standar (ISO 8601) agar tidak ada ambiguitas.
Ringkasan Eksekutif #
Paragraf singkat — maksimal 3–4 kalimat — yang merangkum apa yang paling penting dalam release ini. Ini ditujukan untuk PM dan stakeholder yang tidak akan membaca seluruh dokumen:
## Ringkasan Eksekutif
Sprint 42 berfokus pada perbaikan alur pembayaran dan peningkatan performa
halaman dashboard merchant. Tiga fitur utama dikirim: export laporan bulanan,
notifikasi real-time status order, dan perbaikan race condition pada proses
update status pembayaran. Tidak ada perubahan database schema yang breaking.
Apa Saja yang Dideploy #
Ini adalah bagian paling penting dari release document. Perubahan dikelompokkan berdasarkan jenis — bukan berdasarkan service — agar pembaca dari berbagai background bisa menavigasi dengan mudah:
## Yang Dideploy Sprint Ini
### Fitur Baru
| Fitur | Service | Komponen | Tiket |
|---|---|---|---|
| Export laporan bulanan ke CSV | `report-service` | API, Background Worker | #PROJ-412 |
| Notifikasi real-time status order | `notification-service` | WebSocket, Worker | #PROJ-398 |
| Filter dashboard berdasarkan kategori produk | `dashboard-service` | API, Frontend | #PROJ-401 |
### Perubahan Behavior
| Perubahan | Service | Komponen | Tiket | Dampak |
|---|---|---|---|---|
| Validasi status order diperketat sebelum payment | `order-service` | API | #PROJ-415 | Order berstatus `draft` tidak lagi bisa diproses payment — sebelumnya lolos |
| Timeout worker dinaikkan dari 30s ke 90s | `payment-worker` | Background Job | #PROJ-420 | Mengurangi false-positive timeout pada transaksi besar |
### Bug Fix
| Bug | Service | Komponen | Tiket |
|---|---|---|---|
| Race condition saat update status order bersamaan | `order-service` | API, DB Transaction | #PROJ-408 |
| Memory leak pada worker setelah 24 jam running | `report-service` | Background Worker | #PROJ-411 |
| Response pagination tidak konsisten saat ada filter aktif | `product-service` | API | #PROJ-419 |
### Perubahan Teknis / Infrastruktur
| Perubahan | Service | Komponen | Tiket |
|---|---|---|---|
| Penambahan composite index pada tabel `orders` | `order-service` | Database | #PROJ-416 |
| Upgrade dependency `grpc-go` ke v1.62 | `payment-service` | Semua | #PROJ-422 |
| Penambahan circuit breaker ke external payment gateway | `payment-service` | API | #PROJ-417 |
Service dan Komponen yang Terdampak #
Ringkasan cepat untuk engineer on-call dan QA — area mana saja yang perlu dimonitor dan di mana regression testing harus difokuskan:
## Area Sistem yang Terdampak
**Services:**
- `order-service` — perubahan signifikan (behavior change + bug fix + DB)
- `report-service` — fitur baru + bug fix
- `notification-service` — fitur baru
- `payment-service` — perubahan teknis
- `dashboard-service` — fitur baru (frontend)
**Komponen Sistem:**
- API (5 service)
- Background Worker (3 service)
- Database (1 migration)
- WebSocket (1 service baru)
- Frontend (1 service)
Bagian ini adalah yang pertama dibuka engineer on-call saat incident. Pastikan selalu ada dan akurat. Engineer yang sedang panik di malam hari tidak punya waktu untuk membaca seluruh dokumen — mereka butuh tabel ini.
RFC yang Relevan #
Jika sprint mengandung perubahan arsitektur atau keputusan teknis signifikan, cantumkan referensi RFC — tanpa perlu mengulang isinya:
## RFC yang Diimplementasikan Sprint Ini
| RFC | Judul | Status |
|---|---|---|
| RFC-018 | Migrasi Payment Gateway ke Multi-Provider | Implemented |
| RFC-021 | Circuit Breaker Pattern untuk External API | Implemented |
Jika tidak ada RFC yang relevan, cantumkan — atau hapus bagian ini. Jangan kosongkan tapi biarkan ambigu.
Database dan Migration Notes #
Bagian ini krusial untuk tim infra dan engineer on-call. Perubahan database adalah salah satu penyebab paling umum dari incident pasca-deployment:
## Database & Migration
### Migrations yang Dijalankan
| Migration | Tabel | Jenis | Backward Compatible? | Estimasi Waktu |
|---|---|---|---|---|
| `20260610_add_index_orders_status_created` | `orders` | Tambah index | ✓ Ya | ~30 detik (online DDL) |
### Catatan Penting
- Index ditambahkan menggunakan `CREATE INDEX CONCURRENTLY` — tidak ada table lock
- Tidak ada perubahan schema yang breaking di sprint ini
- Tidak ada data migration — hanya structural change
Jika tidak ada perubahan database, cantumkan eksplisit: “Tidak ada perubahan database di sprint ini.” Jangan biarkan bagian ini kosong — pembaca perlu tahu bahwa ketidakhadiran informasi bukan karena lupa.
Risiko dan Rollback Plan #
Setiap release punya risiko, sekecil apapun. Menuliskan risiko bukan berarti pesimis — ini adalah tanda kematangan engineering:
## Risiko dan Rollback Plan
### Risiko yang Perlu Dimonitor
| Area | Risiko | Kemungkinan | Dampak | Indikator di Monitoring |
|---|---|---|---|---|
| `order-service` | Perubahan validasi bisa reject order yang sebelumnya valid | Rendah | Tinggi | Error rate `/api/orders/payment` melonjak |
| `notification-service` | WebSocket connection bisa overload saat traffic spike | Sedang | Sedang | CPU `notification-service` > 80% |
| DB `orders` | Index creation bisa memperlambat write sementara | Rendah | Rendah | Write latency `order-service` melonjak |
### Rollback Plan
**Jika terjadi masalah kritis dalam 1 jam pertama setelah deploy:**
1. Revert ke image Docker sebelumnya:
```bash
kubectl set image deployment/order-service order-service=registry/order-service:sprint-41
kubectl set image deployment/notification-service notification-service=registry/notification-service:sprint-41
```
2. Verifikasi pod berjalan normal (sekitar 2 menit)
3. Cek error rate kembali normal
4. Buat incident ticket dan tag release owner
**Catatan:** Index yang ditambahkan di database **tidak perlu di-rollback** — aman untuk tetap ada meski service kembali ke versi sebelumnya.
**Estimasi waktu rollback:** < 5 menit
Anti-Pattern Release Document yang Harus Dihindari #
// ✗ Release document yang hanya berisi commit log
"a3f9b2c — fix bug
7d1e4a8 — add feature
2c8f1d9 — update config"
→ Tidak ada konteks, tidak ada traceability ke task, tidak berguna saat incident
// ✓ Setiap perubahan dijelaskan dalam bahasa yang berorientasi dampak,
disertai link ke task dan PR yang relevan
// ✗ Release document dibuat setelah deployment selesai
"Oke sudah deploy, sekarang kita tulis release doc-nya"
→ Detail penting terlupakan, rollback plan tidak sempat dipikirkan
// ✓ Release document ditulis sebagai bagian dari proses deployment —
bukan setelah deployment selesai
// ✗ Release document tidak punya rollback plan
"Kalau ada masalah kita rollback aja"
→ Bagaimana? Berapa lama? Apa yang perlu diperhatikan?
// ✓ Rollback plan harus konkret: perintah yang harus dijalankan,
estimasi waktu, dan catatan tentang data yang tidak bisa di-rollback
// ✗ Satu dokumen untuk banyak sprint
"Release Q2 2026 — Sprint 40, 41, 42"
→ Tidak bisa ditelusuri dengan presisi saat incident
// ✓ Satu sprint = satu release document
// ✗ Release document tidak di-update saat ada hotfix
Deploy Sprint 42 hari Senin → hotfix hari Rabu → release document tidak diperbarui
→ Dokumen tidak lagi mencerminkan kondisi production yang sesungguhnya
// ✓ Hotfix harus dicatat di release document yang sama (dengan label [HOTFIX])
atau dibuat release document terpisah jika perubahannya signifikan
Template Release Document #
Berikut template yang bisa langsung digunakan atau disesuaikan tim:
# Release Document — Sprint [NOMOR]
**Sprint:** Sprint [NOMOR]
**Tanggal Rilis:** YYYY-MM-DD
**Environment:** [Staging / Production]
**Release Owner:** [nama]
**Sprint Board:** [link]
**Status Sprint:** [Done / Partial — sebutkan yang carry over]
---
## Ringkasan Eksekutif
[2–4 kalimat: apa fokus sprint ini, apa yang paling signifikan, ada tidak perubahan breaking]
---
## Yang Dideploy Sprint Ini
### Fitur Baru
| Fitur | Service | Komponen | Tiket |
|---|---|---|---|
| [nama fitur] | `[service]` | [komponen] | #[nomor] |
### Perubahan Behavior
| Perubahan | Service | Komponen | Tiket | Dampak |
|---|---|---|---|---|
| [deskripsi] | `[service]` | [komponen] | #[nomor] | [dampak terhadap user/sistem lain] |
### Bug Fix
| Bug | Service | Komponen | Tiket |
|---|---|---|---|
| [deskripsi bug] | `[service]` | [komponen] | #[nomor] |
### Perubahan Teknis / Infrastruktur
| Perubahan | Service | Komponen | Tiket |
|---|---|---|---|
| [deskripsi] | `[service]` | [komponen] | #[nomor] |
---
## Area Sistem yang Terdampak
**Services:** [daftar service]
**Komponen:** [API / Worker / Database / Frontend / dll]
---
## RFC yang Diimplementasikan Sprint Ini
| RFC | Judul | Status |
|---|---|---|
| RFC-[nomor] | [judul] | Implemented |
---
## Database & Migration
[Jika ada:]
| Migration | Tabel | Jenis | Backward Compatible? | Estimasi Waktu |
|---|---|---|---|---|
| [nama file] | [tabel] | [Tambah kolom/index/dll] | [Ya/Tidak] | [estimasi] |
[Jika tidak ada:] Tidak ada perubahan database di sprint ini.
---
## Risiko dan Rollback Plan
### Risiko yang Perlu Dimonitor
| Area | Risiko | Kemungkinan | Dampak | Indikator |
|---|---|---|---|---|
| [service/komponen] | [risiko] | [Rendah/Sedang/Tinggi] | [Rendah/Sedang/Tinggi] | [metrik yang perlu dipantau] |
### Rollback Plan
[Langkah-langkah rollback yang konkret, termasuk perintah jika relevan]
**Estimasi waktu rollback:** [X menit]
**Catatan:** [hal yang tidak bisa di-rollback, misalnya data migration]
Checklist Sebelum Deploy #
SEBELUM DEPLOYMENT:
□ Release document sudah ditulis dan direview oleh release owner
□ Semua perubahan di dokumen sudah bisa ditelusuri ke task di sprint board
□ RFC yang relevan sudah dicantumkan
□ Database migration sudah diverifikasi backward compatible (atau tidak)
□ Rollback plan sudah ditulis dan bisa dieksekusi tanpa perlu bertanya
SESUDAH DEPLOYMENT:
□ Release document ditandai sebagai "Deployed" dengan timestamp
□ Link ke release document dibagikan ke channel on-call dan stakeholder relevan
□ Monitoring dipantau selama minimal 30 menit pertama setelah deployment
□ Jika ada hotfix dalam 24 jam pertama, release document diperbarui
Ringkasan #
- Release document adalah sumber kebenaran tunggal tentang sebuah rilis — apa yang berubah, di mana, mengapa, dan apa yang harus dilakukan jika ada masalah.
- Tulis release document sebelum deployment, bukan sesudahnya — proses penulisan itu sendiri memaksa kamu berpikir tentang risiko dan rollback sebelum terlambat.
- Kelompokkan perubahan berdasarkan dampak, bukan service — ini memudahkan pembaca dari berbagai background memahami rilis.
- Rollback plan harus konkret — bukan “kita rollback”, tapi perintah apa yang dijalankan, berapa lama, dan apa yang tidak bisa di-rollback.
- Cantumkan database migration secara eksplisit — termasuk jika tidak ada. Kekosongan informasi menciptakan ambiguitas.
- Satu sprint = satu dokumen — jangan gabungkan beberapa sprint, traceability akan sulit.
- Hotfix harus masuk ke release document — production tidak selalu mencerminkan dokumen yang tidak diperbarui.
- Bagian “Area Sistem yang Terdampak” adalah yang paling berharga saat incident — pastikan selalu ada dan akurat.