Dokümantasyon Düzeni

Bu repoda iki ayrı dokümantasyon katmanı var. İkisi farklı okuyuculara yazılır ve farklı kurallarla güncellenir.

docs/: ekip dokümantasyonu

Yapı ve kurallar smartmenu-adisyon-plugin eklentisinden gelir. Eklenti dört servis reposunun hepsine kurulur:

/plugin marketplace add https://github.com/OverfitSoft/smart-menu-adisyon-plugin
/plugin install smartmenu-adisyon-plugin@smart-menu-adisyon-plugin-marketplace

Nereye yazılır

docs/api/ panelin ilk route handler’ıyla birlikte açıldı; şu an tek sayfası Lisans doğrulama. Panelin çağırdığı backend endpoint’leri backend reposunda belgelenir; burada yalnızca Veri ve entegrasyon sayfasındaki tabloda listelenir.

Mevcut mimari sayfaları:

• Genel bakış: reponun sistemdeki yeri, yığın, dizinler, komutlar
• Rotalar ve kabuk: URL’ler, (panel) grubu, Server/Client sınırı, auth
• Ekranlar: her ekranın davranışı ve bağlı olduğu işler
• Tasarım sistemi: token’lar, bileşen sınıfları, ortak parçalar
• Veri ve entegrasyon: fixture’lar, sayaçlar, bekleyen backend işleri

Yeni bir alan (ör. auth geldiğinde) mevcut sayfalardan birine sığmıyorsa yeni bir docs/architecture/<konu>.md açın. Sayfalar tek bir story’ye değil, sistemin bir alanına karşılık gelmeli.

Biçim

Her dosyanın en üstünde şu frontmatter zorunludur:

---
title: <başlık>
updated: <YYYY-MM-DD>
---

• Bir sayfayı değiştirdiğinizde updated alanını da güncelleyin.
• Değişiklik breaking change ise (ör. bir rota kaldırıldı, bir endpoint sözleşmesi değişti) dosyanın en üstüne, frontmatter’ın hemen altına ⚠️ ile başlayan bir uyarı ekleyin.
• Sayfalar sistemin şu anki halini anlatır. Bir değişiklik bir cümleyi yanlış yaptıysa o cümleyi düzeltin; altına düzeltme notu eklemeyin. Geçmiş için git ve changelog.md var.

Ne zaman güncellenir

Bu sayfalar branch’te düzenlenmez. Sprint sonunda, release-flow ile pending notlarından yazılır. Branch’in sorumluluğu notu bırakmaktır.

Nota bakıp yayınlanan sayfa hak eden değişiklikler:

• Yeni rota veya ekran, ekranda davranış değişikliği
• Yeni veya değişen endpoint, gerçek veriye geçen bir ekran
• Tasarım sistemine yeni token veya bileşen
• Kurulum, komut ya da doğrulama adımlarında değişiklik

Ayrı bir “docs PR’ı” açılmaz; yayınlanan doküman dev’e doğrudan atılan tek bir docs: commit’iyle gelir ve main’e merge ile yayına çıkar.

Merkezi docs sitesine aktarım

main’e her push’ta .github/workflows/docs-sync.yml çalışır ve docs/ içeriğini (claude/ hariç) OverfitSoft/smart-menu-adisyon-docs reposundaki content/docs/admin-panel/ altına rsync’ler. DOCS_REPO_PAT secret’ına ihtiyaç duyar. Yalnızca docs/** değiştiğinde tetiklenir.

Yayınlanan doküman dev’de yazılır ama ancak main’e merge ile yayına çıkar; sprint sonundaki release-flow çalıştırması bu yüzden merge’i de kapsar.

docs-sync.yml ve weekly-backup.yml dosyaları yalnızca main branch’inde durur; GitHub arayüzünden oluşturuldular ve dev’e hiç indirilmediler. dev’de aramayın, yeniden eklemeyin.

CLAUDE.md ve docs/claude/: Claude çalışma dokümanları

Claude Code oturumlarının kod yazmadan önce okuduğu, “neden böyle”yi reddedilen alternatiflerle birlikte anlatan İngilizce dokümanlardır.

• Branch’ler CLAUDE.md veya docs/claude/*.md dosyalarını düzenlemez. Paralel branch’ler aynı dosyayı düzenlediğinde her merge’te çakışma çıkıyor ve çözümler metin kaybettiriyordu (SCRUM-198).
• Bunun yerine her issue için docs/claude/pending/<ISSUE-KEY>.md notu bırakılır. Yeni dosya çakışmaz. Biçim: docs/claude/pending/README.md.
• Sprint sonunda biri dev’de /smartmenu-adisyon-plugin:release-flow çalıştırır; notlar önce yayınlanan dokümana (docs/), sonra CLAUDE.md ve docs/claude/ dosyalarına işlenir ve silinir. Aynı çalıştırma dev’i main’e alır; yayınlanan doküman ancak o merge ile merkezi docs sitesine gider.
• dev’e açılan ve bu dosyaları doğrudan düzenleyen PR’lar docs-guard kontrolünden (.github/workflows/docs-guard.yml) geçemez. Gerçekten gerekiyorsa PR’a docs-sync etiketi eklenir.

Bir değişiklikte ne yazılır

Branch’ler dokümanı yazmaz; not bırakır. Tipik bir issue’da (ör. Menü ekranını gerçek veriye bağlamak) commit şunları içerir:

1. Kod değişikliği ve testleri.
2. docs/claude/pending/SCRUM-<n>.md notu (hedef: data.md) — değişikliğin ne olduğu, neyi artık yanlış hale getirdiği ve nedeni.

Yayınlanan doküman (docs/architecture/, docs/api/, docs/changelog.md) bu nottan sprint sonunda üretilir. Her not yayınlanan sayfa hak etmez: dışarıdan birinin bilmesi gereken bir değişiklik (endpoint, şema, sözleşme, yapılandırma, görünür davranış) sayfaya girer; iç yeniden yapılandırma yalnızca docs/claude/ tarafında kalır.

Bu düzen her commit’te doküman yazdıran eski akışın yerini aldı. Eski akışta update-docs skill’i ve her oturum sonunda tetiklenen bir Stop hook’u vardı; aynı iş sprint boyunca defalarca yapılıyor ve çoğu zaman yazacak anlamlı bir şey yokken geliştiriciyi kesiyordu.