Codechu Proje Standartları

Tüm Codechu ürünleri için ortak disiplin kuralları. Programlama dili, hedef platform, lisans modeli veya dağıtım kanalından bağımsız.

İngilizce kanonik: STANDARDS.md. Bu Türkçe paralel — değişiklikler İngilizce kaynağa yapılır, Türkçe güncellenir.

0. Felsefe

"Bir Codechu ürününü bilen kullanıcı, ikincisini de bildiğini hissetsin."

Kimlik, adlandırma, repo yapısı, marka, dokümantasyon konvansiyonları — ürünler arası tahmin edilebilir. Teknoloji kararları (dil, runtime, platform) ürün başına alınır.

1. Bu doküman neyi kısıtlar

Kısıtlar	Kısıtlamaz
Vendor kimliği (ad, namespace, app ID)	Ürün feature seti
Repo konvansiyonları (branch, hook, .gitattributes)	Programlama dili
Marka assetleri (palet, tipografi, logo grameri)	İşletim sistemi / platform
Dokümantasyon yapısı	Dağıtım kanalı
Public vs private repo disiplini	Lisans modeli (açık / kaynak-erişimli / kapalı)
Commit / versioning konvansiyonları	Build tooling

Bir Codechu ürünü CLI, GUI app, library, servis, mobil app, web app veya donanıma yakın firmware olabilir — aynı kimlik kuralları uygulanır.

2. Kimlik (vendor + ürün / library)

Ürünler (son-kullanıcı uygulamaları)

Alan	Kalıp	Not
Vendor	`codechu`	sabit
Product slug	`kebab-case`, 1–2 sözcük	örn. `<product>`
Reverse-DNS App ID	`com.codechu.<ProductName>` (CamelCase)	bundle/app ID kullanan tüm platformlar
GitHub repo	`codechu/<product>`	ürün başına tek repo
Paket registry adı	`codechu-<product>`	dile özgü (PyPI, npm, crates.io...)
Kaynak modül	`<product_module>` (dil konvansiyonu)	Python için snake_case, JS için camelCase vb.
Binary / executable	`<product>` (kısa) veya `codechu-<product>` (vendor-prefix)	UX trade-off

Library'ler (yeniden kullanılabilir bileşenler)

Library'ler dile-özgü olabilir (bir algoritmanın Python wrapper'ı) veya polyglot olabilir (aynı fikir birden çok dilde). Repo adı dil sonekini taşır, böylece birden çok implementasyon yan yana yaşar.

Alan	Kalıp	Örnek
GitHub repo	`codechu/<purpose>-<lang>`	`codechu/events-py`, `codechu/treeviz-rs`, `codechu/xdg-go`
Paket registry adı	`codechu-<purpose>`	`codechu-events` (PyPI), `@codechu/events` (npm), `codechu_events` (crates.io) — registry zaten dile göre kapsamlanmış
Kaynak modül / import	`codechu_<purpose>` (dil konvansiyonu)	`import codechu_events` (Py), `use codechu_events::*` (Rust)

Neden repo adında dil soneki? Çok dilli bir yayımcı bir noktada aynı fikre Rust + Python + Go'da ihtiyaç duyacak (event bus, path soyutlaması, telemetri). Sonek sayesinde codechu/events-py ve codechu/events-rs kardeş repo olarak yaşayabilir, her biri kendi SemVer hattıyla.

Kural: Vendor namespace sistem-düzeyi tanımlayıcılarda zorunlu (reverse-DNS app ID, repo URL, paket registry adları). Son-kullanıcı tanımlayıcılarında (binary, dosya adı) kısa form OK — namespace çakışması yoksa.

Plugin family'ler: bir library'nin temiz bir core'u var ama hepsi birlikte gönderilmesi gerekmeyen variant data ya da adapter'ları varsa (font'lar, locale paketleri, codec'ler), core paket + kardeş codechu-<thing>-<variant> plugin paketleri olarak ayır. Her variant kendi data'sını, lisansını, release döngüsünü taşır.

Repo granülerliği — library başına repo mu, monorepo mu? Belirleyici soru paket sayısı değil, release bağıdır (coupling):

Paketler…	Repo şekli
bağımsız, à la carte gönderilir, her biri kendi SemVer döngüsü (çoğu Codechu lib'i — `cli-py`, `log-py`; core + opsiyonel locale paketleri)	library başına bir repo (varsayılan)
version-lock olur ve lockstep release olur — core artı onsuz kullanılamayan ve birlikte bump olan adapter'lar (ör. UI framework: agnostik core + DOM/native renderer'lar)	tek monorepo, çok paket (workspaces)

Monorepo, React/Vue/Babel şeklidir: tek repo, çok yayınlanan paket, iç bağımlılıklar paket-yöneticisinin workspace mekanizmasıyla çözülür (file: link yok, lokal geliştirmede publish adımı yok). Framework adıyla + dil suffix'iyle isimlendirilir — codechu/ui-ts, paketler core / web / native, yayınlananlar @codechu/ui / @codechu/ui-web / @codechu/ui-native. Version-lock'lu bir aileyi kardeş repolara bölme: bu, repolar arası publish-bump dansını yeniden yaratır (polyrepo-sprawl anti-pattern'i) ve hiçbir izolasyon faydası vermez. Dış tüketiciler yine yayınlanmış pakete bağımlı olur (sınır registry'dir — git-dependency bir monorepo'nun alt-dizinini kuramaz).

3. Dosya sistemi yerleşimi (uygulanabildiğinde)

Diskte kullanıcı verisi tutan ürünler vendor namespace kullanmalı.

Unix / Linux / macOS (XDG tarzı)

~/.config/codechu/<product>/         # config
~/.cache/codechu/<product>/          # cache (yeniden üretilebilir)
~/.local/share/codechu/<product>/    # kalıcı data
$XDG_RUNTIME_DIR/codechu/<product>/  # runtime (socket, pid, lock)

Windows

%APPDATA%\Codechu\<Product>\         # config + kalıcı
%LOCALAPPDATA%\Codechu\<Product>\    # cache + makineye özgü

macOS (XDG kullanmayan native uygulamalar için)

~/Library/Application Support/Codechu/<Product>/   # config + data
~/Library/Caches/Codechu/<Product>/                # cache
~/Library/Logs/Codechu/<Product>/                  # log

Mobil / web / sandboxed

Her platformun native lokasyonu, codechu.<Product> bundle identifier'ı ile namespace'lenir.

Kural: Tek bir dizin açıldığında (örn. Linux'ta ~/.config/codechu/) tüm Codechu ürünleri görünür. Multi-product görünürlüğü tasarım hedefidir.

4. Branding (ürünler arası paylaşılan)

Element	Kural
Renk paleti	Navy `#1d2939` + Gold `#e0a020` + Paper `#fafaf7` (ürün aksenti eklenebilir)
Display font	Ubuntu Sans (veya benzer karakterli, ürüne uygun alternatif)
Mono / kod font	JetBrains Mono (veya platform-native mono fallback)
Logo grameri	Tek-glyph mark + wordmark + lockup
Logo varyantları	`mark.svg`, `mark-knockout.svg`, `mark-mono.svg`, `wordmark.svg`, `lockup-horizontal.svg`, `lockup-stacked.svg`

Detay: BRAND-GUIDELINES.md.

5. Versiyonlama + commit (dil-agnostik)

Kural	Değer
Version şeması	SemVer 2.0
Commit formatı	§5.0'daki ikiden biri, `CONTRIBUTING.md`'de beyan edilir
Release tag	`v<MAJOR>.<MINOR>.<PATCH>`
Pre-release	`-alpha.N`, `-beta.N`, `-rc.N`
Changelog	Keep a Changelog formatı, ya da §5.0'ın düzyazı biçimi

5.0 Geçmiş kimin için yazılıyor

Bir commit konvansiyonu ya ondan bir şey TÜRETEN alete ya da onu ANLAMAK zorunda olan okura hizmet eder; ikisi aynı anda optimize edilemez. Depo başına bilinçli seç ve hangisi olduğunu CONTRIBUTING.md'de söyle. Aynı depo içinde karıştırmak ikisini de vermez.

İkinci okur artık yalnız insan değil. Ajanlar bir sonraki adıma karar vermek için depo geçmişini okuyor ve bu ayrımın TÜRETME değil ANLAMA tarafındalar: fix: correct banner width onlara diff'te zaten göremeyecekleri hiçbir şey söylemez; neyin bozulduğunu ve nasıl fark edildiğini adlandıran bir gövde ise yeniden kuramayacakları kısımdır.

Konvansiyon	Şu durumda seç	Kazandığın	Verdiğin
Conventional Commits + Keep a Changelog	Geçmiş bir GİRDİ: sürümü, changelog'u ve notları release aleti ondan türetiyor	Otomatik release (release-please, semantic-release), makine-okunur değişim türleri	Başlık satırı bir tür ve bir özettir; "neden"e yer kalmaz
Vaka düzyazısı	Geçmiş, sonradan birinin — bir insanın ya da bir ajanın — bir kararı anlamak için okuyacağı kayıt; release'ler kendi kapılarıyla elle kesiliyor	Değişikliği cümle olarak söyleyen bir başlık ve cevap verdiği arızayı adlandıran bir gövde	Hiçbir otomasyon ondan sürüm ya da not türetemez; changelog girdisini sen yazarsın

Vaka düzyazısı seçildiğinde bu bir konvansiyondur, konvansiyonsuzluk değil:

Başlık, değişikliği cümle olarak söyler — tür öneki değil, diff özeti değil.
Gövde vakayı adlandırır: ne bozuktu, nasıl fark edildi, neyin yakalaması gerekirdi. Arkasında vaka olmayan değişiklik bunu söyler.
Kıran değişiklik, changelog girdisinin İLK satırında söylenir; çünkü ! işaretini okuyacak bir makine yok.
Changelog girdisi elle yazılır ve release notudur.

Hiçbiri ötekinin garantilerini atlama ruhsatı değildir. Vaka düzyazısı kullanan bir depo yine v<MAJOR>.<MINOR>.<PATCH> etiketler, yine her release için changelog girdisi yazar, yine kıran değişikliği işaretler — yalnızca bunları bir aletin çıkarmasını beklemez.

5.1 Release kesmek

Yukarıdaki şema bir sayının ne anlama geldiğini söyler. Burası bir sürümün nasıl çıktığını söyler, ve her satırının bedeli ödendi.

Tek komut bütün sürüm kayıtlarını taşır, ve bir test uyuştuklarını iddia eder. Bir sürüm birden fazla yere yazılıyorsa, elle taşımak BAZILARINI taşır. Vaka: bir release paketleme metadata'sını bumpladı ve diğer üç kaydı geride bıraktı; o release'in ürettiği her artefakt, onu üretmemiş bir sürümle damgalandı.
Changelog girdisini tag'den ÖNCE yaz. O, release notudur; hiçbir şey iki kez yazılmaz.
Tetik yalnızca tag'dir, ve onu push etmek insan imzasıdır. Başka hiçbir olay yayımlamaz. Başka hiçbir şey yayımlayabiliyor olmamalı.
Hattı, düşebilecek her şey GERİ ALINAMAZ adımdan önce koşacak şekilde sırala, ve job'a İLK değil SON adımının istediği izni ver. Paket indeksine yayım geri alınamaz ve tekrarlanamaz. Vaka: bir release job'ı indekse yayımladı ve ardından yazma izni olmadığı için forge release'ini oluştururken düştü; arkasındaki bağımlı job hiç koşmadı ve hiçbir yeniden-koşu durumu onaramadı, çünkü yükleme tekrarlanamıyordu.
Koşunun RENGİNİ değil ARTEFAKTI doğrula — ve iki yönde. Yeşil bir koşu yarım kalmış bir release bırakabilir; kırmızı bir koşu gayet sağlam bir sürümün üstünde durabilir. Paket indeksi sayfasını, release sayfasını ve hattın dokunması gereken her şeyi AÇ.
Prosedür aletini ADLANDIRIR, ve alet değişince yeniden okunur. Hattın artık yapmadığı bir adımı anlatan belge, belgesizlikten kötüdür — çünkü izlenir. Vaka: bir release rehberi, workflow tag'den forge release'ini oluşturmaya başladıktan aylar sonra hâlâ operatöre onu elle açmasını söylüyordu.

Başarısız bir release özel mesele değildir: bir sürüm kullanıcılara herhangi bir hâlde ulaştıysa, bunu kimsenin okumadığı bir commit mesajında değil, o sürümün changelog girdisinde söyle.

6. Repo disiplini (her ürün)

Madde	Kural
Default branch	`main` (`master` değil)
Branch protection (olgun ürün)	CI green + 1 review zorunlu
Pre-commit hook	önerilir — bkz. hooks/pre-commit
.gitattributes	text dosyalar için LF normalize
Commit signing	opsiyonel ama release tag'leri için önerilir
İki-katmanlı model	public ürün repoları + private internal / sec-advisories — bkz. §10

7. Dokümantasyon yapısı (her ürün repo'su)

Bu dosyalar beklenir; içerik ürüne göre değişir.

README.md                  # kanonik, İngilizce — **vitrin** (bkz. §7.1)
README.tr.md               # opsiyonel, Türkçe paralel
LICENSE                    # ürünün taşıdığı lisans
CHANGELOG.md               # Keep a Changelog formatı
CONTRIBUTING.md            # katkıcı onboarding (veya "kapalı katkı" notu)
SECURITY.md                # güvenlik açığı bildirimi (kapalı kaynak için de)
CODE_OF_CONDUCT.md         # Contributor Covenant v2.1 referansı (OSS) veya iç sürüm
docs/                      # detay dokümantasyon — manual, referans, recipe
assets/                    # banner, demo cast, diagram, ekran görüntüsü
.github/                   # GitHub-spesifik (template, workflow)

Branding, packaging veya i18n olan ürünler için ek:

docs/BRAND.md, docs/I18N.md, docs/VERSIONING.md, docs/PUBLISHING.md
packaging/                 # platform-spesifik kurulum artifact'leri
po/                        # gettext çevirileri (kullanılıyorsa)

7.1 README vitrin

Kök README.md bir vitrindir, kullanım kılavuzu değil. Bir ziyaretçinin PyPI'da, GitHub aramasında veya registry sayfasında gördüğü ilk şey — son söz değil, ilk izlenim. Buna göre davran.

İlkeler:

Tek çarpıcı görsel üstte — demo cast (asciinema / SVG / GIF), ekran görüntüsü veya temiz bir diyagram. Projenin ekran çıktısı varsa göster. Yoksa, veri akışı / mimari için bir Mermaid veya ASCII diyagram doyurucu bir alternatiftir. Düz metin duvarı kabul edilemez.
Tek hızlı örnek, 5–15 satır, kurulumdan hemen sonra çalıştırılabilir olsun. Her varyantı sıralama. ( overlay/PUBLISHED-VERDICT.md §2 altındaki depolar için ASKIDA — onun yerine ## Run it + gerçek yakalanmış iz gelir.)
Yetenek bullet'ları, API tabloları değil. README yapabildiklerini listeler; docs/API.md her public sembolü listeler.
docs/'a yönlendir — API referansı, recipe'ler, migration, mimari için. Her link tek satır açıklama ile gelsin.
Family tablosu (kardeş Codechu paketleri) — ziyaretçi ekosistemi bulabilsin. ( overlay/PUBLISHED-VERDICT.md §2 altında ASKIDA — kardeş çoğu zaman hiç yayımlanmamıştır; ilişki tek cümleyle söylenir ve repo linklenir.)
Lisans + credits en altta, ve altbilgi aileyi ADLANDIRIR: Part of [Codechu](https://github.com/codechu). Bir arama sonucundan gelen okura bu deponun kardeşleri olduğunu söyleyen tek satır, ve maliyeti bir satır. Vaka: dört tip-iskeletinin ikisinde vardı, sonradan yazılan ikisinde hiç yoktu; yani bir deponun onu taşıyıp taşımaması yazarının hangi iskeleti açtığına kalmıştı.

README'de açık yasaklar:

Tam API referans tabloları yok (docs/API.md'de).
Çok-bölümlü örnek mutfağı yok (docs/RECIPES.md'de).
Tasarım gerekçesi / mimari derin dalış yok (docs/ARCHITECTURE.md veya DESIGN_PRINCIPLES.md'de).
Extension noktası / plug-in kataloğu yok.
Migration rehberi yok (docs/MIGRATION.md'de).

Yumuşak uzunluk hedefi: badge'ler ve görsel sonrası gövde yaklaşık 150 satır'a sığsın. Daha uzunsa içerik docs/'a aittir.

Görsel asset'ler assets/ altında:

assets/
  preview.svg          # README hero statik önizleme (veya banner.svg)
  preview.cast         # asciinema kaydı (opsiyonel)
  preview.gif          # .cast'ten türetilmiş animasyon (opsiyonel)
  diagram-<isim>.svg   # Mermaid render veya el-çizimi mimari
  screenshots/         # GUI ürünleri için

v0.1.0 itibarıyla README sadece-metin olamaz. Ya inline bir Mermaid bloğu ya da assets/ referansı şart. Proje-tipi rehberleri (project-type/LIBRARY.md, TOOL.md, APPLICATION.md) bu kuralı tip-spesifik iskeletlerle yeniden ifade eder.

Render kuralları (ölçüldü, varsayılmadı). Aşağıdakilerin hepsi bir README render edilip sayfaya BAKARAK bulundu; hiçbiri markdown kaynağı okunurken görünmüyor.

README nasıl render ediliyorsa öyle render et. gh api /markdown bir mode alıyor ve iki mod, bu kuralların asıl konusunda birbirine zıt. mode: "gfm" YORUM semantiğidir: her tek satır sonu <br> olur ve başlık çapası hiç üretilmez. mode: "markdown" README'nin aldığıdır: paragraf içindeki satırlar birleşir, başlıklar sayfa-içi linklerin dayandığı çapaları taşır. Tek dosyada ölçüldü: gfm'de kod dışında 116 <br>, markdown'da sıfır. README'yi gfm ile doğrulamak, hiçbir okurun görmeyeceği bir sayfaya bakmaktır — üstelik bir sonraki kuralın konusu olan satır-çökmesini tam da gizler.

GitHub repo sayfasında fold README değildir. 1090 px genişlikte ölçüldü: README ~1080 px aşağıda başlıyor; ilk ekran dosya listesi ve About kutusu. Sonuç: repo description ve topics — dosya değil, ayar — sayfanın en çok okunan metnidir ve README ne kadar iyi olursa olsun oraya ulaşmaz. İkisini de doldur, ve topic'ler description ile çelişmesin.
Aynı paragraftaki iki blockquote satırı tek satıra çöker. İlkinin sonuna <br> koy. Vaka: iki satırlık bir beyit, yazıldığı günden beri tek akan cümle olarak render ediliyordu.
Her badge link olmalı. Hiçbir yere gitmeyen badge, sinyal kostümü giymiş süstür. Vaka: bir README'de dört badge'in üçü ölü görseldi.
Code fence keser, sarmaz. Sütun kenarını geçen satır sessizce kesilir ve okur orada ne yazdığını hiç öğrenemez. Artan uzunlukta bir cetvel render edilerek ölçüldü — pandoc + github-markdown-css, sabit pencere genişliğinde headless Chrome: masaüstü sütunu ~100 karakter alıyor, 390 px telefon ~42. Bu kuralın önceki hâli "~60 karakterin altında" diyordu; dayanağı, kesildiği bildirilen tek bir 58 karakterlik satırdı. O gözlem okurlarımızın kullandığı hiçbir genişlikte tekrarlanmıyor ve ~60 hiçbir şeye karşı ölçülmemişti: telefonda keser, masaüstünde gereksizdir. Okurlarınızın fiilen bulunduğu sütunu bütçeleyin, ve bir sayı yazmadan önce ölçün.
Yazılabilir her şey dil etiketli fence içinde. Dört boşlukla girintilenmiş blok çıplak <pre> olarak render olur, highlight almaz; girintiyi yalnız yazılamayan ASCII için sakla.

7.2 Araştırma & referans alt-ağacı (`docs/research/`)

Bir karar dış literatüre veya bir ajanın eğitim verisinden yeni olabilecek bilgiye dayandığında, araştırmayı repo'da tut — güncel, kalıcı, offline. İki doküman, research saf, sentez ayrı:

docs/research/INDEX.md — dış kaynakların saf kataloğu. Kayıt başına: kimlik satırı (mecra / id / tarih / lisans / cache dosyası) + nötr "bu nedir" + link. Burada Codechu yargısı YOK.
docs/<TOPIC>_LANDSCAPE.md (docs/ kökünde) — bizim sentezimiz: karar (başlık Decision date · Decider · Status), verdict'ler (projenin belirtilen kısıtlarına göre in / out), gerekçe ve kendi ölçümlerimiz. INDEX.md'ye refer eder. Kaynak kaydını renksiz tutmak, sentezi research'i yeniden yazmadan revize etmeye ve nötr gerçeklere karşı denetlemeye izin verir. docs/ARCHITECTURE.md keşfedilebilirlik için landscape dokümanına link verir.
docs/research/fetch.sh — tam kaynakların gitignore'lu docs/research/papers/ cache'ini yeniden kurar (bir kez indir, sonrası offline).
docs/research/figures/ — commit'li, küçültülmüş, atıflı figürler; yalnızca lisansı yeniden-dağıtıma izin veriyorsa gömülür.

Telif kuralları (ayrıca bkz. ai/AGENTS.md §8):

R1 — eserin bütünü commit edilmez. Telifli bir eserin bütünü (PDF / veri seti / tam metin) hiçbir tier'a commit edilmez — yalnızca gitignore'lu cache + yeniden-kurma scripti + orijinale link.
R2 — figür redistribution geçidi. Gömülü figürün yanında lisans + kaynak + yazar bulunur. Lisans üçüncü-taraf yeniden-dağıtıma izin vermiyorsa (ör. arXiv non-exclusive distribution lisansı, "all rights reserved"), figür link-only'dir; public repo yalnızca lisansı izin veren veya sağlam iktibas zeminine oturan (TR FSEK m.35 / EU 2001/29 m.5(3)(d)) figürleri gömer.
Tier önemli. Yayma hakkı umuma arzda tetiklenir; yeniden-dağıtım-izinsiz görseller public-tier repo'ya girmez.

§7.1'in gerekçesinin yeri burasıdır: vitrin README tasarım gerekçesini DIŞARIDA tutar, araştırma alt-ağacı onun indiği yerdir. Bu dosyalar yalnızca GitHub'da render olur (PyPI'a gönderilmez), bu yüzden §7.1 cross-surface kısıtları geçerli değildir. Referans implementasyon: codechu-trace-py.

8. CI/CD baseline

Dil- ve platform-agnostik minimum:

Kontrol	Uygulanır
Lint / format	her ürün, dile özgü tool (ruff/eslint/clippy/gofmt/vb.)
Unit test + coverage threshold	test'i olan her ürün; ≥%60 önerilir
Static security scan	kullanıcı verisi, secret veya yıkıcı işlem yapan ürünler
Translation sync (gettext / eşdeğer)	i18n yapan ürünler
Build artifact (binary, AppImage, MSI, IPA, vb.)	binary dağıtım yapan ürünler
Branch protection	olgun ürünler (post-v1.0 veya geniş kullanıcı tabanı)

Her ürünün .github/workflows/'u bunları barındırır — tooling değişebilir.

9. Lisans politikası (ürün-başına)

Lisans ürün-düzeyi karardır, organizasyon kuralı değil. Bir Codechu ürünü şunlardan biri olabilir:

Açık kaynak permissive (MIT, Apache 2.0, BSD) — community-built
Açık kaynak copyleft (GPL, AGPL) — share-alike
Source-available (örn. PolyForm, BUSL) — ticari kullanım kısıtlı
Proprietary — kapalı kaynak, ticari ürün

Her ürünün LICENSE'ı şartlarını ilan eder. "Codechu default lisansı" yoktur — seçim ürün stratejisine aittir.

10. Public vs private repo disiplini

Codechu iki-katmanlı repo modeli kullanır. Public repolar yayımlanmış, düzenlenmiş içeriği tutar; private repolar strateji, taslak ve yayımlanmamış işleri tutar.

Katmanlar

PUBLIC                                  PRIVATE
─────────────────────────────────       ─────────────────────────────────
codechu/<product>          ✓            codechu/internal           🔒
  yayımlanmış kod + doküman               roadmap (Q1/Q2/yıllık)
  public CHANGELOG                        strateji, fiyatlandırma
  public roadmap (kaba)                   iç metrik, finans
  marketing assetleri                     yayımlanmamış tasarım / deney
                                          müşteri görüşmeleri (NDA)
codechu/codechu-org        ✓            codechu/sec-advisories     🔒
  bu repo (standartlar)                   yamasız güvenlik açıkları + disclosure
codechu/.github            ✓
  organizasyon-geneli profil + default'lar

İçerik yerleşimi

İçerik	Katman	Gerekçe
Yayımlanmış kod	PUBLIC	Zaten ship'lendi
Yayımlanmış dokümantasyon	PUBLIC	Kullanıcıya dönük
Brand assetleri, marketing	PUBLIC	Dışarıdan görünür
Public roadmap (kaba)	PUBLIC	Yön sinyali
Olgunlaşmamış tasarım taslakları	PRIVATE	Yayımdan önce olgunlaştır
Fiyatlandırma, finans, iş kararları	PRIVATE	Yalnız iç kullanım
Müşteri görüşmeleri (NDA)	PRIVATE	Sözleşmesel
Yamasız güvenlik açıkları	PRIVATE	Koordineli disclosure
Rakip analizi, iç strateji	PRIVATE	Gizli
Devam eden marketing A/B testleri	PRIVATE	Pre-launch parlatma izlenimi vermemek için

Senkron disiplini

Private → Public: feature'lar private'da olgunlaşır, public'e tek temiz commit olarak iner. İterasyon gürültüsü private'da kalır.
Public → Private read: maintainer'lar private notlardan public commit'e cross-link verebilir (issue link).
Risk: sızıntı. Credential ve hassas anahtar kelime kontrolü için pre-push hook veya git-secrets.

Maliyet / fayda

GitHub free plan sınırsız private repo sunar — bu disiplin bedavadır, sadece zihinsel disiplin gerektirir.

Sektör pratiği: bağımsız stüdyoların çoğu benzer modeli kullanır.

11. Uluslararasılaştırma (opsiyonel)

Ürünler

Ürünler (son-kullanıcı uygulamaları) i18n yapabilir veya yapmayabilir. Yaparsa:

Kanonik kaynak dili İngilizce'dir
Çeviriler ürün repo'sunun çeviri dizininde yaşar (örn. po/, locales/, i18n/)
Türkçe çeviri önerilir ama zorunlu değildir (çoğu Codechu projesi taşır çünkü katkıcılar Türkçe konuşur)
Diğer diller community-driven

Her ürünün i18n workflow'u docs/I18N.md'de.

Library'ler

codechu/ altında yayımlanan library'ler çıktılarını lokalize etmez.

Exception mesajları, log mesajları ve developer-facing diagnostic'ler English, hard-coded yazılır. Bunlar UI değil, diagnostic'tir; grep'lenebilir, aratılabilir ve locale'lar arası taşınabilir olmalıdır.
Library'ler kullanıcıya çıkan metin üretmez. Semantic data döner (marker'lar, enum'lar, count field'ları, type field'ları); render
- çeviri tüketen uygulamanın işidir.
Library'ler gettext, .po dosyası veya herhangi bir çeviri altyapısı içermez.

İstisna: bir library tüketen uygulamanın araya giremeyeceği bir UI surface'i doğrudan render ediyorsa (CLI help generator, form widget, terminal scaffold), iki seçeneği vardır: (a) belgelenmiş locale-resolution politikasıyla içeride çevirir, veya (b) dependency injection ile translator callback kabul eder. (b) tercih edilir — library loose coupling'i korur, host uygulama kendi i18n stack'i üzerinde kontrolü elinde tutar.

Bu pratik sektörle uyumlu: requests, pydantic, SQLAlchemy, pytest, structlog, tokio, serde, lodash — hiçbiri library seviyesinde i18n yapmaz. Python stdlib'in argparse/optparse'i ve framework'ler (Django, Flask, Click) istisnanın altına girer — son rendering surface'ini onlar sahiplenir.

Referanslar: Microsoft .NET "Best practices for exceptions", jbe2277/waf wiki'sindeki "Should exception messages be localized?" tartışması, API-craft mailing list uzlaşısı.

12. Canlı doküman

Yeni bir ürün edge case ortaya çıkardığında bu dosya PR ile güncellenir. STANDARDS.md'ye dokunan bir PR başlığında breaking change etiketlenir — tüm ürün repolarına yansıyabilir.

13. Katmanlı sözleşmeler

Bu dosya dilden bağımsız, organizasyon geneli katmandır. Onu iki dar katman genişletir:

Katman	Yol	Kapsam
Proje tipi	`project-type/`	Library, tool ya da application; dil farketmez
Dil	`lang/<ad>/`	Dile özgü ekler (bugün Python)
Overlay	`overlay/`	Her tipin benimseyebileceği disiplinler; daraltmaz, ekler

Okuma sırası: STANDARDS → project-type → lang, ardından reponun benimsediği overlay'ler.

14. Aktif repolar

Organizasyon geneli

codechu/codechu-org — bu repo (PUBLIC, standartlar)
codechu/internal 🔒 — strateji, taslak, finans (PRIVATE)

Ürünler

Güncel ürün listesi için README.md.

Yeniden kullanılabilir library'ler (Python)

codechu/events-py — codechu-events — çok-kanallı, thread-safe event bus
codechu/treeviz-py — codechu-treeviz — squarified treemap + sunburst layout
codechu/xdg-py — codechu-xdg — vendor-namespace'li XDG path'leri

FilesExpand file tree

STANDARDS.tr.md

Latest commit

History

STANDARDS.tr.md

File metadata and controls

Codechu Proje Standartları

0. Felsefe

1. Bu doküman neyi kısıtlar

2. Kimlik (vendor + ürün / library)

Ürünler (son-kullanıcı uygulamaları)

Library'ler (yeniden kullanılabilir bileşenler)

3. Dosya sistemi yerleşimi (uygulanabildiğinde)

Unix / Linux / macOS (XDG tarzı)

Windows

macOS (XDG kullanmayan native uygulamalar için)

Mobil / web / sandboxed

4. Branding (ürünler arası paylaşılan)

5. Versiyonlama + commit (dil-agnostik)

5.0 Geçmiş kimin için yazılıyor

5.1 Release kesmek

6. Repo disiplini (her ürün)

7. Dokümantasyon yapısı (her ürün repo'su)

7.1 README vitrin

7.2 Araştırma & referans alt-ağacı (docs/research/)

8. CI/CD baseline

9. Lisans politikası (ürün-başına)

10. Public vs private repo disiplini

Katmanlar

İçerik yerleşimi

Senkron disiplini

Maliyet / fayda

11. Uluslararasılaştırma (opsiyonel)

Ürünler

Library'ler

12. Canlı doküman

13. Katmanlı sözleşmeler

14. Aktif repolar

Organizasyon geneli

Ürünler

Yeniden kullanılabilir library'ler (Python)

7.2 Araştırma & referans alt-ağacı (`docs/research/`)