Menulis PR dan README yang Baik

Mengapa Penulisan Teknis Penting

Dalam code review, deskripsi PR Anda adalah titik masuk bagi reviewer. Deskripsi PR yang baik dapat:

• Membantu reviewer memahami apa yang Anda lakukan dengan cepat
• Mengurangi pertanyaan bolak-balik
• Menunjukkan Anda berpikir matang
• Menghemat waktu Anda saat melihat riwayat 3 bulan kemudian

Tips

Penulisan teknis bukan penulisan kreatif. Ada rumus dan pola, setelah dipelajari Anda bisa menulis dengan sangat baik.

Struktur Standar Deskripsi PR: What/Why/How/Testing

1. What (Apa yang dilakukan)

Ringkasan singkat, satu kalimat.

Refactor authentication flow to support OAuth2 and magic link sign-up

Ekspresi kunci:

• Add X — Menambah fitur baru
• Fix X — Memperbaiki bug
• Refactor X — Menulis ulang kode (tanpa mengubah fungsi)
• Optimize X — Meningkatkan performa
• Implement X — Mengimplementasikan suatu desain

2. Why (Mengapa dilakukan)

Bagian yang paling sering dilupakan. Jelaskan latar belakang dan motivasi.

Why:
- Users requested passwordless sign-up option
- Current session-based auth doesn't scale to multiple domains
- OAuth2 is industry standard for enterprise integrations

3. How (Bagaimana cara melakukannya)

Gambaran umum tingkat tinggi implementasi teknis.

How:
1. Created JWT service using Web Crypto API for signing/verification
2. Replaced SessionMiddleware with AuthMiddleware that validates JWT
3. Added OAuth2 routes for Google/GitHub sign-in
4. Migrated user session storage from cookie to JWT claims

Breaking changes:
- Moved user auth state from server session to JWT (stateless)
- Clients now need to store and send JWT in Authorization header

4. Testing (Bagaimana cara mengujinya)

Jelaskan bagaimana Anda memverifikasi perubahan ini benar.

Testing:
- Manual testing: Verified OAuth2 sign-in with Google and GitHub accounts
- Existing auth tests pass (147 tests)
- Added 23 new tests for JWT and OAuth2 flows
- Load tested with 1000 concurrent requests (no issues)

Template Deskripsi PR

Salin ini, isi bagian kosongnya:

## What
[ringkasan satu kalimat]

[deskripsi lebih detail, 2~3 kalimat]

## Why
- [alasan 1]
- [alasan 2]
- [alasan 3, jika ada]

## How
1. [perubahan 1]
2. [perubahan 2]
3. [perubahan 3]

[jika ada breaking changes, jelaskan di sini]

## Testing
- [pengujian apa yang dilakukan]
- [hasilnya apa]
- [bagian yang belum selesai (jika ada)]

## Related
Closes #123
Depends on #456 (wait for this to merge first)

Jebakan Tata Bahasa Penulisan Teknis

1. Tenses (Kesalahan paling umum)

Prinsip: Present tense untuk apa yang dilakukan kode, past tense untuk perubahan yang Anda buat

Salah	Alasan	Benar
”The function was created to handle X”	Terdengar seperti narasi sejarah	”The function handles X"
"The code will validate input”	Terlalu tidak pasti	”The code validates input”

2. Articles (Kesalahan umum penutur non-Inggris)

Prinsip: Sebutan pertama gunakan “a/an”, selanjutnya gunakan “the”; atau gunakan bentuk jamak untuk menghindari artikel

Salah	Benar
”We refactored authentication flow"	"We refactored the authentication flow"
"Function handles case when user logs in"	"The function handles the case when a user logs in”

3. Kalimat pasif berlebihan

Prinsip: Bahasa Inggris lebih cenderung aktif. Kecuali Anda tidak ingin menyebutkan siapa pelakunya, gunakan kalimat aktif

Pasif (interferensi umum)	Aktif (lebih baik)
“The JWT is generated by the server"	"The server generates the JWT"
"Breaking changes were introduced"	"This PR introduces breaking changes”

4. Perbedaan halus sinonim

Kata	Penggunaan
Add	Menambah fitur baru (belum ada sebelumnya): “Add OAuth2 support”
Implement	Mengimplementasikan desain yang sudah diketahui: “Implement the design from #123”
Refactor	Memperbaiki kode yang ada, tanpa mengubah fungsi: “Refactor auth middleware”
Optimize	Meningkatkan performa: “Optimize query performance”
Fix	Memperbaiki bug: “Fix race condition in cache”

Daftar Periksa Cepat PR

Sebelum mengirim PR, periksa:

• Bagian What menjelaskan perubahan dengan jelas
• Bagian Why memiliki alasan bisnis atau teknis
• Bagian How menjelaskan desain tingkat tinggi
• Bagian Testing menjelaskan cakupan pengujian
• Tidak ada kalimat pasif berlebihan
• Artikel digunakan dengan benar (“the” vs “a”)
• Tenses konsisten
• Link ke issue terkait (jika ada)

Daftar Periksa Cepat README

• Kalimat pertama menjelaskan apa proyek ini
• Ada demo atau screenshot
• Langkah instalasi jelas dan dapat direproduksi
• Contoh penggunaan bisa langsung disalin
• Ada panduan kontribusi (jika menerima kontribusi eksternal)
• Ada lisensi
• Bahasa ringkas (tidak terlalu akademis atau terlalu kasual)