PR Yazma Disiplini

Bu skill, reviewer'ın 2 dakikada karar verebileceği PR açıklamaları yazmayı öğretir. PR'ın asıl muhatabı reviewer; ne iş yaptığını anlatmak senin görevin.

Ne zaman aktif olur

• gh pr create komutu çalıştırılmak üzereyken
• Mevcut PR'ın description'ı düzenlenirken
• PR konusu oluşturulmaktayken

Çekirdek prensip

PR description'ı asıl auditans reviewer'dır. Kod nedir'i zaten söyler; description neden'i, nasıl test edildiğini, riski söyler.

Reviewer'lar zaman darlığında yaşar. Kötü PR açıklaması → merhamet yorgunluğu → yüzeysel review → daha çok bug.

Şablon

## Summary
<1-3 bullet — PR'ın yaptığı şeyin özü>

## Motivation
<Neden yapıyoruz? Hangi sorun, hangi metrik, hangi ticket?>

## Changes
<Kalın bölümler halinde — ne değişti>

## Test plan
- [ ] <adım 1>
- [ ] <adım 2>

## Screenshots / video
<UI değişikliği varsa ZORUNLU>

## Risk & rollback
<Kırmızı bayrak, rollback planı, feature flag durumu>

## Checklist
- [ ] Kendime review yaptım
- [ ] Testler yeşil
- [ ] Breaking change yoksa vurgu, varsa migration notu

Her bölüm nasıl yazılır

Title

• 50-70 karakter
• Conventional commits prefix'i kullan: feat(auth): add SSO with Okta
• Başlık + reviewer'ın anladığı kadar context. Issue numarası başlığa yazmaya gerek yok (description'da).

Kötü: updates, PR for ticket 123, fixes, improvements

İyi: fix(api): return 409 on duplicate order idempotency key

Summary (en kritik bölüm)

1-3 bullet, reviewer'ın başlıktan sonra ilk göreceği şey. PR'ın amacını öz ve net söyler.

## Summary
- Orders endpoint'ine idempotency-key desteği eklendi
- Duplicate key ile gelen istekte cached response döner (200)
- Key TTL 48 saat

Kötü:

## Summary
- Various improvements and bug fixes.

Motivation

Neden. Ticket varsa link, metrik varsa sayı, user feedback varsa alıntı.

## Motivation
Kullanıcılar ödeme sayfasında flaky network nedeniyle aynı siparişi 2
kez oluşturuyordu (geçen ay 47 vaka, destek maliyeti ~8 saat). Idempotency
ile client safe retry yapabilir.

Closes #1204

Changes

Büyük PR'larda kalın başlıklarla grupla. Dosya satır sayısı değil, konu.

## Changes

**API:**
- `POST /orders` idempotency-key header okur
- Duplicate key tespit edilirse cached response

**DB:**
- `orders.idempotency_key` kolonu + unique index
- Migration reversible

**Tests:**
- `orders.idempotency.integration.ts` — happy path + duplicate + TTL

Test plan

Reviewer'ın da çalıştırabileceği somut adımlar. Her biri checkable.

## Test plan
- [ ] `pnpm test orders` — 23 yeşil
- [ ] Manuel: `curl -H "Idempotency-Key: x" ...` iki kez → 2. istek cached dönüyor
- [ ] Staging'de real client ile doğrulama (bağlantı aktif mi?)
- [ ] k6 load test: 500 RPS, 1% key duplication → latency p95 korundu

Screenshot / video

UI değişikliği varsa zorunlu. Before/after tercih. Küçük GIF kullanıcı akışını gösterir.

Backend PR için: kabul edilen response'un ekran görüntüsü / curl çıktısı.

Risk & rollback

Açık, doğrudan. Gizleme.

## Risk & rollback
- **Risk:** Schema migration. Production'da `CONCURRENTLY` index build, downtime yok.
- **Feature flag:** `orders.idempotency` (default off)
- **Rollback:** Flag off → davranış eskiye döner. Migration reversible.

Checklist

## Checklist
- [x] Kendime review yaptım (diff'i okudum)
- [x] `pnpm test` yeşil
- [x] `pnpm lint` yeşil
- [x] Tarayıcıda çalıştırıp tıkladım (UI değişikliği varsa)
- [x] Breaking change yok — varsa migration notu eklendim
- [x] Dokümantasyon güncel (README, API spec)

Büyük PR'ı bölme

500+ satır değişen bir PR reviewer için cezadır. Böl:

1. Preparation PR: sadece refactor, davranış aynı
2. Feature PR: yeni davranış, küçük yüzey
3. Cleanup PR: eski kodu kaldır

Her biri ayrı review, ayrı merge. Feature flag ile koordine.

Draft vs Ready for review

• Draft: henüz review isteme. CI yeşil olsun, kendi review'unu yap, açıklamayı tamamla → sonra "Ready for review".
• Ready: tüm testler geçti, kendi review'unu yaptım, reviewer'a zaman ayırtmaya değer.

Reviewer'a taslak PR gönderme — saygısızlık.

Etiket / metadata

Projenin kurallarına uy:

• breaking-change, needs-docs, blocked gibi etiketler
• Milestone / project
• Reviewer request — kim, kaç kişi
• Issue linking (Closes #, Fixes #, Refs #)

İyi PR örneği

# feat(search): add Turkish-aware fuzzy matching

## Summary
- Fuse.js + özel Turkish tokenizer ile Türkçe çekim formları da eşleşir
- Zero-result oranı %34 → hedef %15
- A/B test ile kademeli rollout (10% → 50% → 100%)

## Motivation
Mobilde search funnel'ı %34 zero-result üretiyordu (analytics dashboard).
Kullanıcı "arabaların" yazdığında "araba" sonuçları gelmiyordu.

Closes #720, refs RFC-018.

## Changes

**Search core:**
- `lib/search/tokenizer.ts` — Turkish suffix stripper
- `lib/search/index.ts` — Fuse.js yapılandırma (threshold 0.3, location ignored)
- Lunr kaldırıldı

**Feature flag:**
- `search.turkishFuzzy` (off/10/50/100)

**Benchmark:**
- Indexing 500K item: 2.1s (öncesinde 3.4s)
- Query latency p95: 45ms → 52ms (kabul)

## Test plan
- [x] `pnpm test search` — 48 yeşil
- [x] 50 test query manuel (fixtures/queries.json)
- [x] A/B dashboard hazır — primary metrik `zero_result_rate`
- [ ] Staging'de 10% traffic ile 24h gözlem

## Screenshots
![before-after](https://...)

## Risk & rollback
- Feature flag ile kapatılabilir
- Eski Lunr index 1 hafta backup'ta duracak
- Rollback: `search.turkishFuzzy=0` → Lunr'a dönüş

## Checklist
- [x] Self-review
- [x] Testler yeşil
- [x] Docs güncel (search.md)
- [x] RFC-018 linked
- [x] Breaking change yok

Kötü PR örneği

# Updates

did some improvements to search. also fixed a bug. closes #720

• Başlık belirsiz
• Summary yok
• Motivation yok
• Test planı yok
• Risk yok
• Reviewer 5 dakika diff'e dalacak, sonra "LGTM" yazacak — şans oyunu

Review'a cevap verirken

• Her review yorumuna ya çözüm commit'i ya açıklama ile yanıt ver
• "Fixed" / "Done" yazarken commit SHA'sı ekle
• Karşı çıkıyorsan neden: "bu yaklaşım X nedeniyle tercih edildi, trade-off Y"
• Reviewer'ı bekletme — 24 saat max

Merge öncesi son kontrol

• CI tamamen yeşil (testler, lint, build, security scan)
• Branch up-to-date with base (rebase veya merge)
• Tüm conversation'lar resolve edildi
• Approval count yeterli (takım kuralı)
• Merge strategy: squash (önerilen) / merge / rebase — projeye uygun
• Squash commit mesajı anlamlı (default PR title yetersizse düzelt)

Sonrası

• Merge sonrası deploy izle (prod metric, error rate)
• Rollback şartı tetiklenirse beklenmeksizin revert
• PR'dan öğrenilenleri kendi mental model'ina ekle (retrospektif)