Katkı Rehberi (Contributing Guide)

Humindx projesine katkıda bulunmak isteyen geliştiriciler için branch, commit, PR ve kod kalitesi standartları.

1. Branch Stratejisi (Git Flow)

main                    ← Production-ready kod. Direkt push yasak.
├── develop             ← Aktif geliştirme branch'i. PR ile merge.
│   ├── feat/US-201-misty-chat       ← Yeni özellik
│   ├── fix/US-302-json-parse-error  ← Bug fix
│   ├── refactor/scoring-engine      ← Refactoring
│   ├── docs/phase-1-roadmap         ← Dokümantasyon
│   └── test/golden-dataset-eval     ← Test ekleme/güncelleme
├── release/0.1.0       ← Release candidate
└── hotfix/critical-rls-bypass       ← Production acil düzeltme

Branch İsimlendirme

<tip>/<kısa-açıklama>

Tip	Kullanım	Örnek
`feat/`	Yeni özellik	`feat/US-201-misty-chat`
`fix/`	Bug düzeltme	`fix/US-302-json-parse-error`
`refactor/`	Davranış değiştirmeyen yapısal iyileştirme	`refactor/scoring-engine`
`docs/`	Sadece dokümantasyon	`docs/api-contracts-update`
`test/`	Sadece test ekleme/güncelleme	`test/golden-dataset-v2`
`hotfix/`	Production acil düzeltme	`hotfix/rls-bypass`

Kurallar:

User Story ID varsa branch adına ekle: feat/US-201-misty-chat
Kebab-case kullan (tire ile ayır, küçük harf)
Kısa ve açıklayıcı tut (max 50 karakter)

2. Commit Mesaj Formatı (Conventional Commits)

<tip>(<kapsam>): <açıklama>

[opsiyonel gövde]

[opsiyonel footer]

Tipler

Tip	Açıklama	Örnek
`feat`	Yeni özellik	`feat(chat): implement misty chat WebSocket handler`
`fix`	Bug düzeltme	`fix(scoring): apply daily cap per room, not globally`
`refactor`	Davranış değiştirmeyen kod değişikliği	`refactor(sanitizer): extract NER logic to separate module`
`test`	Test ekleme/güncelleme	`test(rls): add social room isolation assertion`
`docs`	Dokümantasyon	`docs(architecture): update data-flow-diagrams`
`chore`	Build, CI, bağımlılık güncellemesi	`chore(deps): upgrade fastapi to 0.115`
`perf`	Performans iyileştirme	`perf(rag): add HNSW index for vector search`

Kurallar

Açıklama satırı max 72 karakter
İngilizce yaz (kod ve commit dili İngilizce, dokümantasyon Türkçe)
Emir kipi kullan: "add", "fix", "update" (not "added", "fixes")
Gövde (body) gerekiyorsa boş satırla ayır
Breaking change varsa footer'a BREAKING CHANGE: ekle

Örnekler

feat(chat): implement FOG_LIFTED WebSocket event

When a misty chat session ends, the Cold Path analysis triggers
a FOG_LIFTED event that reveals the agent type and shift values
to the frontend via WebSocket.

Closes US-203

fix(scoring): enforce daily cap per room, not globally

Previously the ±4.0 daily cap was applied across all rooms.
Now each room (PROFESSIONAL, DISCOVERY) has its own cap,
as specified in scoring-algorithms.md Section 5.

Closes #142

3. Pull Request (PR) Kuralları

PR Açma

bash

# Branch'ini push et
git push origin feat/US-201-misty-chat

# PR oluştur (GitHub CLI)
gh pr create --base develop --title "feat(chat): implement misty chat" --body "..."

PR Şablonu

markdown

## Özet
- [US-201] Sisli Sohbet WebSocket handler implementasyonu

## Değişiklikler
- Chat Engine'e WSS endpoint eklendi
- Redis session yönetimi (TTL: 24h) implementasyonu
- FOG_LIFTED event yayını

## Test
- [ ] Unit testler geçiyor (`pytest tests/`)
- [ ] RLS izolasyon testi geçiyor
- [ ] Lokal Docker ortamında E2E test yapıldı

## İlgili Doküman
- `docs/modules/b2c-engine.md` Bölüm 3
- `docs/architecture/data-flow-diagrams.md` Akış A

Merge Kuralları

Kural	Detay
Review	En az 1 onay (approve) gerekli
CI	Tüm deterministik testler geçmeli
LLM Eval	Prompt değişikliği varsa Direction Accuracy > %85, Hallucination < %2
Conflict	Merge conflict'i PR sahibi çözer
Squash	`develop`'a squash merge yapılır (temiz git history)
Rebase	`main`'e merge: release branch'i üzerinden, squash değil regular merge

4. Kod Kalitesi Standartları

4.1. Linter ve Formatter

Servis	Dil	Araç	Konfigürasyon
API Gateway	TypeScript	ESLint + Prettier	`.eslintrc.js`, `.prettierrc`
Psikometrik Motor	Python	Ruff (lint + format)	`ruff.toml`
SQL	SQL	sqlfluff	`.sqlfluff`

4.2. Pre-commit Hooks

yaml

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: lint-ts
        name: ESLint (TypeScript)
        entry: npx eslint --fix
        language: system
        files: '\.tsx?$'
      - id: lint-py
        name: Ruff (Python)
        entry: ruff check --fix
        language: system
        files: '\.py$'
      - id: no-secrets
        name: Secret Detection
        entry: detect-secrets-hook
        language: python
        files: ''

4.3. Güvenlik Kuralları

.env, credentials.json, API key'leri asla commit etme. .gitignore'da tanımlı.
SQL sorgularında parameterized query kullan — string concatenation yasak.
Kullanıcı girdisi her zaman sanitize edilmeli (XSS, SQL injection).

5. Dosya ve Klasör Yapısı

humindx/
├── docs/                    ← Dokümantasyon (Türkçe)
├── services/
│   ├── api-gateway/         ← NestJS (TypeScript)
│   │   ├── src/
│   │   ├── test/
│   │   └── package.json
│   └── psychometric-engine/ ← FastAPI (Python)
│       ├── app/
│       ├── tests/
│       ├── eval/            ← Golden Dataset ve eval scriptleri
│       ├── prompts/         ← Ajan sistem prompt'ları
│       └── requirements.txt
├── infra/                   ← Docker, Terraform (ileride)
├── .github/workflows/       ← CI/CD pipeline'ları
└── docker-compose.yml

6. Linear Issue Yönetimi ve Label'lar

Issue takibi Linear üzerinden yapılır. Dokümanlar (phase-1-mvp.md) donmuş referanstır — güncel durum her zaman Linear'dadır.

6.1. Hiyerarşi

[EPIC] Parent Issue (Örn: SIM-167 Kimlik ve Onboarding)
  └── Sub-Issue (Örn: SIM-143 US-101 Kayıt)

Epik'ler iş kapsamını gruplar, sub-issue'lar implementasyon birimleridir.

6.2. Katman Label'ları

Her issue, hangi ekibin/geliştiricinin ilgileneceğini belirten katman label'ları ile etiketlenir. Bir issue birden fazla label alabilir.

Label	Renk	Kapsam	Örnek Issue
`frontend:b2c-mobile`	Mavi	Son kullanıcı mobil uygulaması — Sisli Sohbet, DNA kartı, Pasaport (React Native / Flutter)	Quick-Scan UI, Proof Loop animasyonu, Upsell ekranı
`frontend:b2b-panel`	Koyu Mavi	İK yönetici dashboard'u — İşe Alım, Yetenek Yönetimi, Ekip Topolojisi (Next.js)	Aday listesi, Yönetim Reçetesi, Turnover Radarı
`frontend:dev-portal`	Açık Mavi	API lisanslama, Webhook yönetimi, Partner geliştirici arayüzü (Next.js)	Partner onboarding, API key yönetimi
`frontend:admin`	Mor	İç yönetim paneli (ileride kullanılacak)	—
`backend:hot-path`	Turuncu	API Gateway + Chat Engine (NestJS/Go) — WSS, Auth, REST endpoints	Sisli Sohbet WSS, Proof Loop, RAG bypass
`backend:cold-path`	Mor	Psikometrik Motor (FastAPI/Python) — Scoring, Sanitization, Vectorization	EMA algoritması, PII maskeleme, LLM Inference
`infra`	Gri	Docker, CI/CD, DB migration, RLS, Audit Trail	docker-compose, RLS CI testi, Audit immutability

6.3. Mevcut Tip Label'ları

Label	Kullanım
`Bug`	Hata düzeltme
`Feature`	Yeni özellik
`Improvement`	Mevcut özelliğin iyileştirilmesi

7. İletişim ve Süreç

Konu	Kanal
Bug raporu	GitHub Issues (label: `bug`)
Özellik talebi	GitHub Issues (label: `enhancement`)
Mimari tartışma	GitHub Discussions veya ADR PR'ı
Acil production sorunu	Slack #humindx-oncall

8. Definition of Done (Per-PR Checklist)

Her PR, merge öncesi aşağıdaki kontrolleri geçmiş olmalıdır. PR şablonuna kopyalayıp işaretleyin — boş bırakılan madde gerekçe ile açıklanmalıdır.

8.1. Kod ve Test

[ ] Deterministik testler geçiyor (pytest / jest)
[ ] Değişen kod için yeni/güncel unit test eklendi
[ ] Linter + formatter temiz (ESLint/Ruff/sqlfluff)
[ ] TODO / FIXME bırakılmadıysa veya bırakıldıysa Linear issue'ya bağlandı

8.2. Güvenlik ve Gizlilik (Shift-Left Gate)

[ ] Yeni endpoint / sorgu ekleniyorsa RLS politikası güncellendi mi? (architecture/context-rooms-design.md)
[ ] PII taşıyan yeni alan varsa security/vector-privacy.md sanitization pipeline'ı kapsıyor mu?
[ ] Yeni veri işleme faaliyeti varsa security/threat-model.md güncellenmesi gerekiyor mu? (gerekiyorsa ayrı PR açıldı)
[ ] Audit-relevant event eklendiyse audit_events yazımı testte doğrulandı (audit-trail.md)

8.3. AI/LLM Değişiklikleri

[ ] Prompt veya model versiyonu değiştiyse ilgili Model Card güncellendi (Tier 2 sonrası zorunlu)
[ ] Golden Dataset üzerinde eval çalıştırıldı: Direction Accuracy > %85, Hallucination < %2 (testing-strategy.md)
[ ] Prompt değişikliği ile regression farkı PR açıklamasına eklendi

8.4. Dokümantasyon

[ ] Davranışsal değişiklik varsa ilgili docs/*.md güncellendi
[ ] Mimari karar içeriyorsa yeni ADR açıldı (guides/architecture-decisions/)
[ ] API kontratı değiştiyse modules/api-contracts.md güncellendi

8.5. Review

[ ] En az 1 approve alındı
[ ] backend:cold-path etiketli PR'larda reviewer + modeli test etmiş olmalı (prompt değişikliği için)

Not: Bu checklist MVP aşaması içindir. Enterprise satış başladığında §8.6 olarak "Compliance" bloğu eklenecek (DPIA etki analizi, NIST AI RMF kontrol mapping'i).

9. Sürüm ve Release Akışı

Per-service semver, CHANGELOG, git tag ve GitHub release release-please (ADR-004) tarafından otomatik üretilir. Geliştiricinin tek yapması gereken: doğru Conventional Commit yazmak.

9.1. Commit Kapsamı = Bump Kapsamı

Commit mesajının (<kapsam>) kısmı, hangi paketin version'ı bump edileceğini belirler. Yanlış kapsam = yanlış bump.

Kapsam	Etkilediği paket	Git tag formatı
`api`	`services/api-gateway`	`api-gateway-v0.3.1`
`engine`	`services/psychometric-engine` (ileride)	`psychometric-engine-v0.1.4`
`mobile`	`clients/b2c-mobile` (ileride)	`b2c-mobile-v1.2.0`
`panel`	`clients/b2b-panel` (ileride)	`b2b-panel-v0.4.0`
`ci`, `docs`, `chore`	Bump yok (CHANGELOG'a bile girmeyebilir)	—

Path-based yedek: Yanlış kapsam yazılsa da, release-please commit'in hangi dosyaları değiştirdiğine bakar. Bir feat(api): commit'i services/api-gateway/ dışına dokunmuyorsa sadece api-gateway bump edilir; dokunuyorsa birden fazla paket etkilenebilir. Yine de scope'u doğru yazmak birincildir.

9.2. Bump Kuralı (Semver)

Commit tipi	Bump
`fix(<kapsam>): ...`	patch (0.2.1 → 0.2.2)
`feat(<kapsam>): ...`	minor (0.2.1 → 0.3.0)
`perf(<kapsam>): ...`	patch
`feat(<kapsam>)!: ...` veya gövdede `BREAKING CHANGE:`	major (0.2.1 → 1.0.0) — pre-1.0 aşamada minor bump
`refactor`, `docs`, `test`, `chore`, `ci`	Bump yok

9.3. Akış (Git-Flow ile)

feat/* → develop         (CI çalışır; backend-ci vb.)
develop → release/X.Y.Z  (Simetri promotion PR'ı açar)
release/X.Y.Z → main     (merge)
  └─ main push → release-please Release PR açar
       │  - <component>-vX.Y.Z tag + GitHub release
       │  - CHANGELOG.md güncellemesi
       │  - manifest + package.json bump
       ▼
    CI yeşil olunca Simetri elle "Squash and merge" atar
       │ (GitHub Free + private repo'da native auto-merge yok — ADR-004 §7)
       ▼
    main → develop       (back-merge PR — yine elle merge)

9.4. Mobil Tarafta Build Number

Marketing version (app.json veya package.json) release-please tarafından güncellenir. Native build number (iOS CFBundleVersion, Android versionCode) EAS Build tarafında otomatik artırılır — release-please'in kapsamı değildir.

9.5. Milestone Tag'ları (Manuel)

İş milestone'ları (MVP, B2B Beta, GA vb.) release-please tarafından yönetilmez. docs/roadmap/'teki faz dosyası güncelleme PR'ı merge olunca Simetri elle tag atar:

bash

git tag -a v0.1.0-mvp -m "MVP Phase 1 — feature frozen"
git push origin v0.1.0-mvp

Bu tag'lar per-service tag'lardan farklıdır ve projenin bütüncül durumunu işaretler.

9.6. Release PR'ı Reddetmek

Hatalı bir bump gördüysen release-please PR'ını kapat — bir sonraki main push'ta yeniden açılır. Eski PR'ın yorumuna neden kapattığını yaz (ileride autorelease: tagged label'ı ile back-merge işlemi kaybolmasın).

Son Güncelleme: 2026-04-16 — §9 Release akışı ve release-please entegrasyonu eklendi. Sahip: Simetri.

Katkı Rehberi (Contributing Guide) ​

1. Branch Stratejisi (Git Flow) ​

Branch İsimlendirme ​

2. Commit Mesaj Formatı (Conventional Commits) ​

Tipler ​

Kurallar ​

Örnekler ​

3. Pull Request (PR) Kuralları ​

PR Açma ​

PR Şablonu ​

Merge Kuralları ​

4. Kod Kalitesi Standartları ​

4.1. Linter ve Formatter ​

4.2. Pre-commit Hooks ​

4.3. Güvenlik Kuralları ​

5. Dosya ve Klasör Yapısı ​

6. Linear Issue Yönetimi ve Label'lar ​

6.1. Hiyerarşi ​

6.2. Katman Label'ları ​

6.3. Mevcut Tip Label'ları ​

7. İletişim ve Süreç ​

8. Definition of Done (Per-PR Checklist) ​

8.1. Kod ve Test ​

8.2. Güvenlik ve Gizlilik (Shift-Left Gate) ​

8.3. AI/LLM Değişiklikleri ​

8.4. Dokümantasyon ​

8.5. Review ​

9. Sürüm ve Release Akışı ​

9.1. Commit Kapsamı = Bump Kapsamı ​

9.2. Bump Kuralı (Semver) ​

9.3. Akış (Git-Flow ile) ​

9.4. Mobil Tarafta Build Number ​

9.5. Milestone Tag'ları (Manuel) ​

9.6. Release PR'ı Reddetmek ​