Katkı Vermek

Çalışma tarzı

Bu repo şunları tercih eder:

• kodlamadan önce okumak
• küçük ve hedefli diff'ler
• açık sahiplik sınırları
• minimum abstraction
• görünür fail durumları

En önemli katkı kuralları

• Çalışan sistemleri gelişigüzel yeniden yazmayın.
• Spekülatif yeniden mimari yerine eklemeli hardening yap.
• Proje yönü açıkça değişmeden local-first ve paper-first varsayımlarını koru.
• Frontend kabuklarını Python runtime etrafında ince tut.

Önerilen katkı akışı

1. en küçük sahip modülü oku
2. eşleşen docs ve .ai notlarını oku
3. minimum ama gerçek faydalı değişikliği yap
4. önce hedefli testleri çalıştır
5. davranış değiştiyse daha geniş doğrulamaya çık
6. varsayımlar değiştiyse docs ve .ai notlarını da güncelle

Commit tarzı

Conventional commit tarzı tercih edilir; çünkü release otomasyonu ve tarihçe daha okunabilir kalır. Örnekler:

• feat: add locale-aware docs routing
• docs: expand runtime and onboarding guidance
• fix: clarify docs feedback forwarding state

Release otomasyonu main üzerindeki conventional commit'leri okur. Feature commit'leri minor release, fix/perf/docs/build/ci/chore commit'leri patch release üretir; ! veya BREAKING CHANGE: major release anlamına gelir.

Sadece main otomatik olarak pyproject.toml, workspace package sürümleri ve CHANGELOG.md değiştirir. Diğer branch'ler version preview çalıştırır ve test binary'leri için prerelease tag/release kayıtları yayınlayabilir:

• main: v0.9.5 gibi stabil SemVer tag'leri
• V1, V2 gibi integration branch'leri: v0.9.6-next.9870+gabc1234 gibi next prerelease'leri
• feature branch'leri: v0.9.6-beta.9870+gabc1234 gibi beta prerelease'leri

v0.9.5.9870 gibi dördüncü SemVer core segment kullanma; CI build kimliği prerelease ya da build metadata içinde yaşamalı.

İlk stabil main release'i semantic-release sonucunu tracked pre-1.0 baseline'a floor etmek zorunda kalırsa release workflow tag atmadan önce baseline changelog bölümü üretir; böylece CHANGELOG.md boş kalmaz.

CI ve release kontrolleri

Pull request'ler ve korunan branch'lerde şu kontroller yeşil kalmalı:

• Python core: uv sync, Ruff, Pyright, Pytest ve PyInstaller smoke build
• Web GUI: pnpm workspace install, lint, typecheck ve production build
• Docs: pnpm workspace install, lint, typecheck ve static export
• TUI: pnpm workspace install ve Ink entrypoint syntax check
• Version Check: semantic-release preview ve SemVer uyumlu branch artifact kimliği
• Binaries: branch testleri için macOS ve Windows PyInstaller artifact'leri; v* tag'lerinde stabil GitHub Release'e, branch push'larında prerelease GitHub Release'e eklenir

Strict Pyright/Pylance açık, ama repo hâlâ belgelenmiş eski backlog'u eritiyor. CI ve release kontrolleri scripts/check_pyright_baseline.py regression gate'ini kullanır: mevcut baseline'ın üzerindeki yeni diagnostics fail eder; type-clean işler baseline'ı script, roadmap ve .ai state içinde birlikte düşürmelidir.

Docs güncellemesi ne zaman işin parçasıdır

Şu durumlarda docs aynı branch içinde güncellenmeli:

• komut ya da workflow değiştiyse
• frontend ile runtime sınırı değiştiyse
• yeni bir guardrail ya da tasarım kuralı geldiyse
• onboarding beklentileri hareket ettiyse

Bu repo için iyi PR neye benzer

• diff odaklı kalır
• operatöre görünen davranış doğrulanır
• docs implementasyonla eşleşir
• gelecek katkı veren aynı kuralı yeniden keşfetmek zorunda kalmaz