README Dosyası Nasıl Yazılır? GitHub Projenizi Anlatmanın Temelleri
Bir GitHub deposu için okunabilir README hazırlayın: amaç, ön koşullar, kurulum, örnek kullanım ve güvenlik notları.
Bir GitHub deposunu açtığınızda kodu anlamadan önce genellikle şu soruların cevabını ararsınız: Bu proje ne yapıyor? Benim işime yarar mı? Nasıl çalıştırabilirim? README dosyası bu sorulara ilk cevapları veren kısa bir giriş kapısıdır.

İyi bir README çok uzun veya süslü olmak zorunda değil. Gerçek projeyi doğru anlatması, adımları anlaşılır sırada vermesi ve okuyucuyu bilmediği şeyleri tahmin etmeye zorlamaması daha değerlidir. Bu rehberde küçük bir örnek üzerinden ilk README'nizi hazırlayacağız.
README.md nedir?
README.md, genellikle bir projenin kök dizininde bulunan açıklama dosyasıdır. .md uzantısı Markdown biçimini ifade eder; başlık, bağlantı, liste ve kod örneği gibi öğeler basit metinle yazılır. GitHub uygun konumdaki README dosyasını repo ziyaretçisine gösterebilir.
README, kaynak kodun yerine geçmez ve uygulamanın kurulumunun otomatik olarak sorunsuz olduğu anlamına gelmez. Buradaki talimatların gerçek sürümle güncel tutulması gerekir. Çalışmayan veya eksik bir kurulum komutu, hiç komut olmamasından daha fazla zaman kaybettirebilir.
1. Önce ne yaptığını söyleyin
İlk birkaç satır, okuyucunun projeyi anlaması için yeterli olsun:
# Bakım Takibi
Küçük ekiplerin cihaz bakım tarihlerini ve notlarını takip etmesine
küçük bir web arayüzüyle yardımcı olan örnek uygulama.
Bu örnek hayalî bir proje anlatır; kendi deponuzda gerçekten bulunan işlevleri yazın. “En gelişmiş çözüm” gibi doğrulanamayan iddialar yerine hangi sorunu kimin için çözdüğünü açıklayın. Uygulamanın henüz deneysel veya geliştirme aşamasında olduğunu belirtmek de kullanıcıya doğru beklenti sağlar.
2. Ön koşulları ve sürümleri belirtin
Çalıştırmadan önce gereken araçları listeleyin: örneğin PHP sürümü, veritabanı ve paket yöneticisi. Fakat bir projede kullanmadığınız teknoloji veya sürümü örnek diye README'nize koymayın. Hangi sürümü gerçekten test ettiğinizi yazın; “her sistemde çalışır” gibi genellemelerden kaçının.
Kurulum işletim sistemine göre değişiyorsa bu farkı gösterin. Okurun boş bir proje klasöründe mi yoksa mevcut bir kurulumda mı çalıştığını açıkça belirleyin. Gerçek sistemlerde veri kaybına neden olabilecek komutlara özellikle dikkat edin.
3. Kurulumu adım adım ve güvenli anlatın
Okur için temel sıra genellikle depoyu almak, bağımlılıkları kurmak, örnek yapılandırmayı hazırlamak ve uygulamayı çalıştırmaktır. Komutları projeye uygun hâle getirin ve mümkünse temiz bir deneme ortamında test edin.
1. Depoyu bilgisayarınıza alın.
2. Gerekli bağımlılıkları kurun.
3. Örnek ortam dosyasını kendi ortamınıza göre hazırlayın.
4. Yerel geliştirme sunucusunu başlatın.
Gerçek bağlantı adresleri ve gizli anahtarları README'ye yazmayın. .env.example gibi bir örnek sunuyorsanız içine sadece temsili veya boş değerler koyun. Üretim veritabanına bağlanmayı gerektiren bir kurulum örneğini varsayılan yol olarak önermeyin.
4. Kısa bir kullanım örneği verin
Bir API ise örnek istek ve beklenen yanıtı, komut satırı aracıysa bir örnek komutu, web uygulamasıysa ilk yapılacak işlemi gösterebilirsiniz. Gösterdiğiniz çıktı güncel sürümde üretilebilmeli. Bir özelliğin yalnızca belirli yetkilerle veya ek ayarla çalıştığını biliyorsanız bunu da belirtin.
Ekran görüntüsü ekleyecekseniz görüntüde müşteri adı, e-posta, erişim anahtarı veya özel kayıt bulunmadığını kontrol edin. Görselin okuyucuya ne anlattığını söyleyen bir alternatif metin eklemek de yararlıdır.
5. Destek, katkı ve lisans bilgisi
Başkalarının hata bildirebileceği yeri ve katkı kurallarının nerede bulunduğunu anlatın. Bir lisans varsa gerçekten hangi lisansın geçerli olduğunu belirtin; başkasının kodunu kullanıyorsanız kendi başınıza yeniden lisanslayabileceğinizi varsaymayın. Projeye uygun bir LICENSE dosyası ve gerekiyorsa ayrı katkı yönergeleri kullanabilirsiniz.
Yayınlamadan önce son kez okuyun
Depoyu ilk defa gören birinin gözünden kontrol edin: Projenin ne olduğu belli mi? Kurulum adımları eksiksiz mi? Örnekler gerçek mi? Gizli bilgiler yanlışlıkla yazılmış mı? Bağlantılar doğru sayfalara gidiyor mu?
README tek seferlik bir vitrin değildir. Proje değiştikçe onu da güncellemek, hem kullanıcıların hem de birkaç ay sonra projeye dönen sizin işinizi kolaylaştırır.
Kaynaklar: GitHub: README dosyaları hakkında · GitHub: Temel yazma ve biçimlendirme
BİRLİKTE ÖĞRENELİM
Yorumlar
Henüz yorum yok. Düşünceni paylaşarak sohbeti başlatabilirsin.
Bir Yorum Bırak.
Katkılarını ve deneyimlerini duymak isterim. Yorumlar yayınlanmadan önce incelenir.