Panduan Kontribusi
Menjalankan proyek & tes
Section titled “Menjalankan proyek & tes”npm install # juga menjalankan prisma generatenpm run db:test:up # Postgres tes di 127.0.0.1:5433npm run lintnpm run typecheck # next typegen + tscnpm run test:unitnpm run test:integrationnpm run test:e2e # build + Playwright (viewport HP)Muat variabel tes sebelum menjalankan tes integrasi/e2e secara manual: set -a; . ./.env.test; set +a.
Pola kode
Section titled “Pola kode”- Logika bisnis di service (
src/features/<domain>/*.ts), bukan di komponen atau route. Service menerimaactor = { id }dan membaca ulang peran dari DB. - Service mengembalikan
Result(ok(...)/fail(code, message, fields)), bukan melempar error untuk kasus wajar. - Input dari luar divalidasi dengan Zod di service; Server Action hanya merapikan tipe dan memotong panjang.
- Komponen yang dipakai lintas fitur ditaruh di
src/ui/, utilitas murni disrc/lib/. - Penamaan domain memakai bahasa Indonesia (
terbitkan,tutup,hapusDraf,peran,tenggat), mengikuti istilah pengguna. - Fitur baru wajib punya tes: unit untuk aturan murni, integrasi untuk service (termasuk izin dan balapan bila relevan), e2e untuk alur utama.
- Perubahan schema = file migrasi SQL baru di
prisma/migrations/, plusnpx prisma generate.
Pesan commit
Section titled “Pesan commit”Format Conventional Commits: jenis(area): ringkasan singkat.
| Jenis | Untuk |
|---|---|
feat |
fitur baru / perubahan perilaku yang terlihat pengguna |
fix |
perbaikan bug |
perf |
peningkatan kinerja |
refactor |
perapian kode tanpa perubahan perilaku |
style |
tampilan kecil tanpa perubahan logika |
test |
tes saja |
docs |
dokumentasi |
chore |
seed, konfigurasi, rilis |
Contoh: feat(aspirasi): pin to top, fix(form): re-check status under lock.
Pembaruan dokumentasi
Section titled “Pembaruan dokumentasi”Dokumentasi tidak diperbarui di setiap commit. Pembaruan dilakukan sekaligus saat diminta (mis. menjelang laporan atau rilis), disusun dari riwayat commit sejak pembaruan dokumentasi terakhir, dalam satu commit docs: ...:
CHANGELOG.md→ Belum dirilis: satu baris bahasa awam untuk setiap perubahan yang terlihat pengguna (Ditambahkan / Diubah / Diperbaiki / Keamanan). Refactor, tes, dan seed internal tidak perlu.docs/enhancement-log.md: baris untuk setiap permintaan dari pengguna/PIC (ID berurutan, status, versiBelum dirilis). Beberapa permintaan kecil dalam satu pesan boleh digabung satu baris.docs/teknis/*: bila arsitektur, izin, alur deploy, atau tabel/kolom berubah.- README: bila cara menjalankan atau fitur tingkat tinggi berubah.
Semantic Versioning MAJOR.MINOR.PATCH:
- Selama pengembangan 0.x.y; 1.0.0 saat aplikasi resmi dipakai (go-live).
- MINOR naik bila sudah terkumpul fitur baru/perubahan berarti; PATCH bila rilis hanya berisi perbaikan.
- Perubahan kecil (teks, penyesuaian tampilan, perbaikan kecil) tidak memicu versi baru. Cukup dicatat di “Belum dirilis” dan ikut di rilis berikutnya.
- Rilis dilakukan saat perubahan sudah banyak, biasanya bersamaan dengan merge
dev→main. Langkahnya di operasional.md.
Riwayat versi awal (diberikan mundur): 0.1.0 Fondasi, 0.2.0 Aspirasi, 0.3.0 Form & Survei, 0.4.0 Polling + Peran dinamis, 0.5.0 penyempurnaan (Mode Kelola, tautan form, foto, Aspirasi masuk, template polling), 1.0.0 go-live (rancangan ulang tampilan Serdik, aktivasi lewat Google P3MD, Laporkan masalah).