Humindx Docs

Appearance

ADR 004: Release Otomasyonu — release-please ​

  • Tarih: 2026-04-16
  • Durum: Kabul Edildi (Accepted)
  • İlgili Bileşen: CI/CD / Versiyonlama / Changelog
  • Bağlam Dosyaları: ../../CONTRIBUTING.md, ../../../CLAUDE.md, 003-monorepo-with-npm-workspaces.md, 002-dual-track-development.md
  • Sahip: Simetri

1. Bağlam ve Problem ​

Monorepo içinde iki tipte "sürüm" konusu var:

  1. Her servis/istemci için per-package semver (services/api-gateway@0.3.1, ileride services/psychometric-engine@0.1.4, clients/b2c-mobile@1.2.0). Conventional Commits'ten otomatik türetilmeli.
  2. Proje milestone versiyonu ("MVP Phase 1 Done" gibi).

Ayrıca:

  • Conventional Commits zaten CONTRIBUTING.md §2'de benimsendi.
  • Git-Flow benimsenmiş durumda (develop → main).
  • Deploy Railway üzerinden git-tabanlı (Docker registry push zorunlu değil).
  • EAS Build mobil tarafta build number'ı kendi yönetecek; release-please sadece marketing version ile ilgilenir.

2. Karar ​

release-please (googleapis/release-please-action v4) kullanılacaktır. Per-package bump, CHANGELOG, git tag ve GitHub release otomasyonunu kapsar. Release PR akışı ile "otomatik commit değil, otomatik öneri" modeli uygulanır — bu da ADR-002 (dual-track) felsefesine uyar.

Proje (root) versiyonu için ayrı release-please bileşeni KULLANILMAYACAK. Gerekçeler §4'te; monorepo'larda root-level semver anti-pattern olarak değerlendirilir.

Milestone'lar, Simetri tarafından elle atılan anlamlı git tag'ları (v0.1.0-mvp, v0.2.0-b2b-beta) ile işaretlenir; içerik docs/roadmap/ altındaki faz dosyalarında zaten mevcuttur.

3. Değerlendirilen Alternatifler ​

3.1. Changesets (@changesets/cli) ​

  • Artıları: npm ekosisteminde en yaygın; explicit changeset dosyası yazma pratiği yüksek kalite CHANGELOG üretir; monorepo için mükemmel.
  • Eksileri: Python servisi (FastAPI) ve mobile native versiyon desteği yok. Polyglot için ikinci bir araç eklemek gerek.
  • Neden seçilmedi: Humindx polyglot (TS + Python + mobile). Tek araçla kapsanması operasyonel basitlik için değerli.

3.2. semantic-release ​

  • Artıları: Tam otomatik (commit'e göre publish).
  • Eksileri: Monorepo desteği tarihsel olarak zayıf; "otomatik publish" felsefesi ADR-002'deki insan onayı gate'iyle çatışır; yanlış Conventional Commit formatı sessiz yanlış bump'a yol açar.
  • Neden seçilmedi: Risk/kontrol dengesi bizim için kötü.

3.3. Lerna (legacy mod) ​

  • Artıları: Klasik.
  • Eksileri: Artık aktif gelişim yok; npm workspaces + Nx/Changesets ile değiştirildi.
  • Neden seçilmedi: Ölü araç.

3.4. Manuel (npm version + git tag) ​

  • Artıları: Sıfır tool.
  • Eksileri: Disiplin ister; CHANGELOG ayrıca üretilmelidir; monorepo'da hangi paketin bump'ı gerektiği tartışma konusu.
  • Neden seçilmedi: Pre-dev fazında tolere edilebilir ama hızla kaos yaratır.

3.5. git-cliff + elle bump ​

  • Artıları: Güçlü CHANGELOG üretici.
  • Eksileri: Sadece changelog — versiyon bump ve GitHub release ayrı tool ister.
  • Neden seçilmedi: Tek bir çözüme birleştirmez.

4. Neden Proje-Level Semver Yok? ​

Monorepo'larda root-level semver genellikle karışıklık yaratır:

  1. Anlamsız semantik: api-gateway 0.7.2 iken mobile 1.3.0 — "projenin 0.5.0'ı" ne demek? Dağılımın neresine karşılık geliyor?
  2. Bump tetikleyicisi belirsiz: Hangi commit root'u bump eder? Her servis commit'inde mi? Bu çifte-sayım ve yanlış mesaj verir.
  3. İş modeli milestone'u semver değildir: "MVP Phase 1 Done" bir iş kararı; semver patch/minor/major'a tercüme edilemez.

Endüstri pratiği: Per-package semver + human-named milestone tags. Humindx bunu takip eder.

5. Akış (Git-Flow ile Entegrasyon) ​

feature branch ──PR──> develop  (CI: lint/test/build, release-please YOK)
                          │
                          │ release/X.Y.Z promotion PR (Simetri açar)
                          ▼
                         main    (release-please burada çalışır)
                          │
                          │ release-please Release PR açar
                          │  - Component başına bump (CC'den)
                          │  - CHANGELOG.md güncellemesi
                          │  - manifest + package.json güncellemesi
                          ▼
                   Auto-merge (CI yeşilse)
                          │
                          ▼
              git tag: api-gateway-v0.3.1
              GitHub Release (CHANGELOG içeriği)
                          │
                          │ back-merge main → develop (otomatik PR)
                          ▼
                    develop senkron

6. Implementasyon Unsurları ​

6.1. release-please-config.json ​

  • release-type: node per TS servisi
  • release-type: python ileride services/psychometric-engine için
  • release-type: node mobile için (marketing version; EAS Build native'i ayrı ele alır)
  • include-component-in-tag: true → api-gateway-v0.3.1 gibi scoped tag

6.2. .release-please-manifest.json ​

Mevcut versiyonları tutar; release-please günceller. İlk satır: "services/api-gateway": "0.0.1".

6.3. Workflow (.github/workflows/release-please.yml) ​

  • Tetik: main'e push
  • Permissions: contents: write, pull-requests: write
  • GITHUB_TOKEN yeterli (bot PR'ı için); Simetri PAT gerekmez.

6.4. Merge Politikası ​

Release PR'ı elle squash-merge edilir. GitHub'ın native auto-merge feature'ı GitHub Free + private repo kombinasyonunda desteklenmediği için atlandı (bkz. §7 "Dezavantajlar"). Solo/küçük ekipte tek tıklamalık merge pratikte bir maliyet değil — otomasyonun %95'i (bump + changelog + tag + release) zaten release-please'te.

İleride Team plan'a geçiş veya PAT-tabanlı custom workflow düşünülebilir; şu an gereksiz karmaşa.

6.5. Commit Kapsamı = Bump Kapsamı ​

CONTRIBUTING.md §9 bunu kodifiye eder:

  • feat(api): ... → sadece services/api-gateway bump
  • feat(mobile): ... → sadece clients/b2c-mobile bump
  • Path-based fallback: commit hangi dosyaları değiştiriyorsa o component etkilenir

7. Sonuçlar ve Gelecek Etkileri ​

Avantajlar:

  • Tek araç, tüm versiyonlama + CHANGELOG + release işini yapar
  • Polyglot (Node + Python + mobile) destekli
  • Release PR felsefesi insan onayına açık
  • Git-Flow ile doğal uyum
  • Railway/Coolify gibi git-tabanlı deploy'larla uyum (Docker push zorunlu değil)

Dezavantajlar ve Riskler:

  • release-please v4 öğrenme eğrisi var (config'i ilk defa kuranlar için)
  • Yanlış Conventional Commit scope'u → yanlış component bump (örn: feat(api): aslında mobile kodunu değiştiriyorsa karışır)
  • İlk Release PR'ı bootstrap için manuel müdahale isteyebilir (initial version)
  • GitHub Actions'a "Create and approve PRs" izninin repo-level'da açık olması gerekir; kapalı bırakılırsa release-please sessiz çalışmaz ("GitHub Actions is not permitted to create or approve pull requests" hatası)
  • GitHub Free + private repo'da native auto-merge yok — release PR'ı elle squash-merge edilir; Team plan veya PAT-tabanlı custom workflow gelecek seçenek

Hafifletme Stratejisi:

  • Commit scope yanlışlıklarını path-based otomatik component atamasıyla kapat (file-level değişiklik de sayılır, scope sadece ipucu)
  • CODEOWNERS release-please workflow'una uygulanır → bypass zor
  • İlk release denemesi develop klonu sahte PR'ı üzerinden yapılır (not: live repo'da test öncesi)

Ne Zaman Yeniden Değerlendirilir?

  • Release PR'lar sürekli çatışıyor veya manuel rebase gerektiriyorsa
  • Polyglot component sayısı 6+ olursa (Nx release entegrasyonu düşünülebilir)
  • Docker image push otomasyonu gerekirse (workflow uzatılır, yeni karar değil)
  • Değişen Conventional Commits yorumu veya breaking-change taksonomisi ihtiyacı olursa

Simetri tarafından inşa ediliyor.