release-management

Release Management

Ortak Doktrin

agents/shared/severity-rubric.md ve agents/shared/escalation-matrix.md default-load sayılır (agents/coordination.md §11). Bu skill'in çıktısı Critical / High / Medium / Low + kanıt formatında olmak zorunda — spekülatif Critical yasak. Sahiplik dışı bulgu ilgili agent'a delege; karar yetkisi eşiği aşılırsa kullanıcı onayı zorunlu.

Ne Zaman Kullanılır

• Tag / version cut zamanı (planlı release)
• Hotfix prod'a girecek (kısa formlu release readiness)
• Multi-service koordineli release (deploy sırası kritik)
• Code freeze giriş/çıkış
• Release notes / changelog draft
• Feature flag aç/kapat sırası belirleme
• Sunset (eski sürüm kapatma) planı

Workflow

1) Bağlam topla

• Önceki tag: git describe --tags --abbrev=0
• Önceki tag'dan beri commit listesi: git log <prev>..HEAD --no-merges --format="%h %s"
• Etkilenen path'ler: git diff --name-only <prev>..HEAD
• Açık PR: gh pr list --state merged --base main --search "merged:>=<prev-date>"
• Açık issue: kapanması beklenen hangileri (linked PR)

2) Semver kararı

Commit <type>	Bump
feat: ...	minor (0.x → 0.x+1.0 veya 1.x → 1.x+1.0)
feat!: ... veya body'de BREAKING CHANGE:	major
fix: ... / perf: ...	patch
refactor: ... (davranış aynı)	patch (genelde) veya skip
docs: ... / test: ... / ci: ... / chore: ...	skip (release notes'ta opsiyonel)
feat: ... + breaking detected	major (yine de)

Pre-release: 0.x.y döneminde minor da breaking olabilir; semver "0.x is unstable" konvansiyonu — yine de CHANGELOG'da BREAKING not.

3) CHANGELOG draft

Keep a Changelog formatı:

## [X.Y.Z] - YYYY-MM-DD

### Added
- `feat:` commit'leri buraya (subject + scope, kullanıcıya hitap)

### Changed
- `refactor:` davranış değiştiren ya da görünür API değişen commit'ler
- `feat:` ek özellik ama mevcut davranış değişti

### Fixed
- `fix:` commit'leri

### Deprecated
- Sunset planı: ne, ne zaman, alternatif

### Removed
- Bu sürümde kaldırılan özellikler (önceden deprecated olanlar)

### Security
- CVE fix, dependency bump, auth düzeltme

[X.Y.Z]: https://.../tag/vX.Y.Z

Kurallar:

• Kullanıcı dilinde — internal jargon yok.
• Commit hash değil etki — "Cache TTL'i 60s'ten 300s'a çıktı" > "abc123 commit".
• Migration adımları ayrı bölümde (varsa).
• Breaking change belirgin (CAPS veya emoji + "BREAKING").
• Link'ler: PR/issue numaraları.

4) Release readiness checklist

Code

• Branch yeşil (CI tüm job).
• Coverage düşmedi (önceki release'e göre).
• Test paketi ana iş kolu yeşil.
• Performance benchmark sapma < %5 (perf-critical değişimde).
• Security scan (gitleaks/trivy/grype) clean.
• Dependency audit (CVE high/critical = 0).

Doc

• CHANGELOG güncel.
• README breaking change'leri yansıtıyor.
• Migration guide (breaking varsa).
• API doc / OpenAPI güncel.
• Runbook update (yeni alert/dashboard varsa).

Deploy

• Migration ayrı PR + merge edilmiş.
• Feature flag default state explicit (genelde off, flag aç ayrı release).
• Canary/rolling stratejisi seçildi.
• Health probe var.
• Rollback komutu planda yazılı.
• Sunset/deprecation planı yayınlandı (varsa).

İletişim

• Release notes draft (kullanıcı dilinde).
• Internal announcement (Slack/email).
• Customer-facing announcement (varsa).
• Status page hazır.

5) Multi-service koordinasyon

Birden fazla servis aynı release window'unda:

• Deploy sırası: shared dep önce (DB → Backend → Frontend → Infra).
• Compatibility window: API contract her iki sürümü bir süre destekler.
• Feature flag ile cross-service feature aç/kapat.
• Rollback bağımlılığı: bir servis rollback diğerini de etkiliyor mu?
• Communication channel: tek release coordinator + kanal.

6) Sunset / deprecation lifecycle

• T-90 gün: deprecation duyurusu, alternatif yol açık.
• T-30 gün: deprecation header (Sunset: <date>), warning log.
• T-0: kaldırma. Önceden kaldırılma niyeti dokumented.
• API'de Sunset HTTP header (RFC 8594) + Link: <...>; rel="successor-version".

7) Feature flag lifecycle

• Created: flag açıldı, default off.
• Rolled out: %5 → %25 → %50 → %100 (fail rate izle).
• Stabilized: %100 + tüm metric yeşil > 14 gün.
• Removed: flag kodu kaldırıldı (uzun yaşayan flag = teknik borç).
• Flag inventory: yaş, sahip, durum dashboard.

8) Tag + push

# Semver karar verildi: vX.Y.Z
git tag -a vX.Y.Z -m "Release vX.Y.Z

<release notes summary>"

# Push tag (kullanıcı onayı: git push --tags)
git push origin vX.Y.Z

GitHub Release oluştur:

gh release create vX.Y.Z \
  --title "vX.Y.Z" \
  --notes-file CHANGELOG-X.Y.Z.md \
  --target main

Checklist

• Önceki tag'dan beri commit listesi alındı
• Semver bump kararı verildi (kanıtla — feat/fix/breaking)
• CHANGELOG draft hazır (Keep a Changelog formatı)
• Release readiness checklist (code/doc/deploy/iletişim) yeşil
• Multi-service koordinasyon (varsa) deploy sırası belli
• Sunset/deprecation planı (varsa) duyurusu yapıldı
• Feature flag durumu inventory'de
• Tag mesajı yazıldı, push kullanıcı onayı
• GitHub Release notları kullanıcı dilinde
• Rollback komutu yanıbaşında (planda yazılı)

Antipattern

• Subject == hash: "Release v1.4.0: 23 commit" — kullanıcı için anlamsız.
• Breaking change saklama: feat: bump prevented; rollback fragmented.
• Tag yokken release notes: tag → release notes → tag pattern; release notes önce, tag onaydan sonra.
• Migration deploy ile aynı PR: ayrı PR, önce merge.
• Feature flag default-on production'a doğrudan: progressive rollout (%5/%25/%50/%100).
• Sunset duyurusu deploy ile aynı gün: 90/30/0 gün lifecycle.
• Rollback komutu sözel: yazılı + test edilmiş plan.
• latest tag: mutable; rollback delili kayıp (rules/cicd.md).
• v1.4.0-fix1 semver ihlali → v1.4.1 patch.
• Release sırasında force push: history rewrite + tag bozulması.
• Coverage düşür-and-release: regresyon olasılığı belgelenmiş.

Örnek Agent Davranışı

User: /release-plan
Agent (release-manager):
1. Önceki tag: v1.3.2 (2026-04-12).
2. Commit listesi: 47 commit.
   - 12 feat (3'ü breaking — `feat!`)
   - 18 fix
   - 9 refactor
   - 8 chore/docs/ci
3. Semver: BREAKING var → major bump → v2.0.0 öner.
4. Migration impact: API v1 endpoint'leri 6 ay sunset planlı; v2 paralel yaşar.
5. Release readiness:
   - CI yeşil ✓
   - Coverage %72 → %74 ✓
   - Migration PR'ları merge ✓ (3 ayrı)
   - Feature flag: yeni flag `subscription_orders` default off ✓
   - Performance: p95 sapma -%3 (iyileşme) ✓
6. CHANGELOG draft hazır (yukarıdaki format).
7. Multi-service: api-svc (v2.0.0) + checkout-svc (v1.7.0) + frontend (v3.4.0) — DB → API → Frontend sırası.
8. Sunset: v1 API → 2026-11-12 (T+180).
9. Tag mesajı + GitHub Release draft hazır.
10. Kullanıcı onayı: tag push + release publish.

Çıktı Formatı

# Release Plan: vX.Y.Z

## Semver Kararı
- Bump: <patch|minor|major>
- Kanıt: <breaking var/yok, feat sayısı, fix sayısı>

## CHANGELOG Draft
<Keep a Changelog formatı>

## Migration Impact
- Breaking: <kullanıcıya>
- Sunset: <eski sürüm tarih>
- Compatibility window: <gün>

## Readiness Checklist
- [ ] CI yeşil ...
- [ ] ...

## Multi-Service Koordinasyon
- Deploy sırası: ...
- Bağımlılık: ...

## Rollback Planı
```bash
# revert komutu
helm rollback ...

İletişim

• Internal:
• External:
• Status page:

Tag + Release

git tag -a vX.Y.Z -m "..."   # kullanıcı onayı sonrası push
gh release create vX.Y.Z ...