Dokümantasyon altyapısı

Münderecat documentation foundation: static-root-loader-v1

Bu sayfa, dokümantasyon uygulamasının içerikleri uygulama içine kopyalamadan repo kökündeki docs/ ağacından okuduğunu doğrulayan ilk proje kaydıdır.

Kullanıcı, geliştirici ve proje içerikleri ayrı audience ağaçlarında yayımlanır; yazım ve içerik review sorumlulukları aşağıdaki canonical rehberde tanımlıdır.

Sürüm sözleşmesi

Dokümantasyonun güncel ve tarihî artifact kimliği docs/project/releases/docs-release-manifest.json kaydından gelir. Güncel sayfalar kök rotalarda yayımlanır; tarihî snapshot’lar yalnız kaydedilmiş Git nesnesi ve kilitli araç zincirinden /versions/<release-id>/ altında yeniden üretilir. Snapshot artifact’ı immutable’dır ve ancak açık bir manifest değişikliğiyle destek listesinden çıkarılabilir.

Preview deployment

Pull request preview’ları Cloudflare Pages Direct Upload ile yayımlanır; ancak canonical ürün yine apps/docs/dist/ statik dizinidir. Secretsiz PR build’i ile credential taşıyan deploy işi ayrı workflow’lardır. Trusted deploy yalnız exact workflow artifact’ını indirir, PR kodunu çalıştırmaz ve statik-only doğrulaması başarısızsa upload yapmaz. Sağlayıcı seçimi ve privilege sınırı ADR-020 kaydında, operasyon adımları geliştirici preview rehberinde tutulur.

Browser kalite kapısı

Authored rotalar tek Chromium production-build oturumunda axe WCAG A/AA, klavye, responsive navigation, yatay taşma ve dark/light tema davranışı açısından doğrulanır. Hata halinde screenshot ve trace saklanır; işletim sistemi font rasterization’ına bağımlı golden görseller kalite kapısı yapılmaz. Yerel ve CI giriş noktası make docs-browser-check hedefidir.

Kimlik ve locale sözleşmesi

doc_id dil ve URL’den bağımsız kalıcı doküman kimliğidir. Türkçe canonical kaynaklar mevcut docs/<audience>/... ağacında ve prefixsiz URL’lerde kalır; çeviriler docs/locales/<locale>/<audience>/... kaynağından /<locale>/<audience>/... rotasına derlenir. Aynı doc_id, çeviriyi Türkçe canonical sayfaya bağlar; canonical eşi olmayan çeviri build’i durdurur.

URL değişikliği kimliği değiştirmez. Eski adresler sayfanın redirect_from metadata’sında tutulur, canonical/redirect çakışmaları build öncesi reddedilir ve çeviri namespace’leri Türkçe redirect’lerden ayrılır. Her release base’i için indexlenmeyen statik redirect sayfasına çevrilir.

Yazım ve ownership

Audience, doğruluk, çeviri, generated içerik ve review sorumluluklarının canonical kaynağı yazım ve review rehberidir. Frontmatter owners kalıcı işlevsel rolü, CODEOWNERS ise GitHub review yönlendirmesini ifade eder. CODEOWNERS tek başına semantik onay veya bağımsız quorum kanıtı değildir; public remote kuralları ayrıca etkinleştirilmelidir.