README Nedir?
Yayın: · Son güncelleme:
README Nedir? Kısaca
README, bir yazılım projesinin kök klasöründe bulunan ve projenin ne işe yaradığını, nasıl kurulup çalıştırılacağını ve nasıl katkı verileceğini anlatan, genellikle Markdown biçiminde yazılmış tanıtım dosyasıdır.
README nedir?
README, İngilizce "beni oku" anlamına gelir ve bir projenin vitrinidir. GitHub ya da GitLab'da bir depoyu açtığınızda dosya listesinin altında görünen metin, bu dosyanın içeriğidir. Çoğu zaman README.md adıyla ve Markdown biçimiyle yazılır.
Bir projeyi ilk kez gören kişi birkaç dakika içinde karar verir: bu proje işime yarar mı, nasıl çalıştırırım? README bu sorulara cevap vermiyorsa ziyaretçi büyük ihtimalle başka projeye geçer.
İçinde neler olmalı?
Sık kullanılan bölümler şunlardır:
- Proje adı ve kısa açıklama: Tek paragrafta ne işe yaradığı.
- Kurulum: Gerekli araçlar ve adım adım komutlar.
- Kullanım: Basit bir örnek ya da ekran görüntüsü.
- Yapılandırma: Ortam değişkenleri ve ayar dosyaları.
- Katkı ve lisans: Nasıl katkı verileceği ve hangi lisansla dağıtıldığı.
Örneğin döviz kurlarını çeken küçük bir komut satırı aracı yazdınız diyelim. README'de önce aracın ne yaptığını tek cümlede anlatırsınız. Sonra pip install komutunu, ardından kur USD gibi bir kullanım örneğini ve çıktısını gösterirsiniz. Okuyucu bu üç bilgiyle aracı beş dakikada deneyebilir.
Nelere dikkat etmeli?
En yaygın sorun, eskimiş kurulum adımlarıdır. Proje yeni bir sürüme geçtiğinde README'deki komutları da güncellemek gerekir. Kurulum adımlarını temiz bir bilgisayarda baştan sona denemek, eksikleri hemen ortaya çıkarır.
İş arayan geliştiriciler için README ayrıca bir tanıtım aracıdır. GitHub profili üzerinden incelenen projelerde, açık ve düzenli bir README işverene özen hakkında doğrudan fikir verir.
Sıkça Sorulan Sorular
README dosyası hangi formatta yazılır?
En yaygın biçim Markdown'dır ve dosya adı README.md olur. Düz metin (README.txt) ya da reStructuredText (README.rst) biçimleri de kullanılabilir.
Her projede README olmalı mı?
Paylaşılan, ekipçe geliştirilen ya da ileride tekrar açılacak her projede olması önerilir. Kısa bir README bile birkaç ay sonra projeye dönen kişinin işini kolaylaştırır.