Neden README dosyasını eklemeliyiz !
Neden README dosyasını eklemeliyiz !
GitHub , GitLab ve Bitbucket gibi web depolama servisleri kullanıyorsanız README dosyasına aşina olduğunuzu düşünüyorum.
Web depolama servisleri ve versiyon kontrol sistemi hakkında bilgi almak istiyorsanız aşağıdaki yazımı okumalısınız.
Versiyon kontrol sistemleri kısa ve anlaşılır şekilde anlatmaya çalışacağım.medium.com
Peki nedir bu README dosyası ?
- Yukarıdaki belirtilen web depolama servislerinde birinde bir proje oluşturduğunuzda projenizin açıklama kısmıdır.
- Projenizi ziyaret eden bir kullanıcının projeye tıklandığında önüne gelen sayfadır.
Yani açılış sayfasında görünen sayfadır.
Readme dosyasında neler olmalıdır ?
- Projeni genel bir özeti.
- Projeyi nasıl indireceğimiz.
- Projeyi nasıl çalıştıracağımız.
- Testler nasıl çalıştırılır.
- Proje geliştirilirken hangi teknolojilerden yararlanıldığı.
- Projeye eklemek istedikleriniz.
- Projeyi geliştirenler.
- Lisans.
Örnek bir tema aşağıdadır.
Readme dosyasını nasıl oluştururuz ?
- Projeyi oluştururken
- Projemizi oluşturduktan sonra , projenin içini elimizle readme dosyası oluşturmak.
Projenizi bilgisayardan githuba göndermede zorlanıyorsanız aşağıdaki yazıma göz atabilirsiniz.
1.Github’a kayıt yaptırın ve yeni bir repository oluşturun.medium.com
Oluşturduğumuz Readme dosyasını ismi Readme ya da Readme.md olabilir.Genelde README.md olarak kullanılır.
— > Buradaki .md markdown anlamına gelir. Markdown bize düz yazı olarak yazdıklarımızı html dönüştürerek hızlı düzenlemeler yapmamızı sağlar. Çünkü html de hızlı düzenleme yapmak zordur.
Markdown için kaynaklar.
Bir kaç örnekle Readme dosyasının önemini görelim :D
- Rails projenizde default gelen readme sayfasını değiştirmemek.(kötü)
2. Gerekli açıklamalar yapılmış.(iyi)
3. Bir truffle projesinde readme dosyası bile yok.(kötü)
4.Hiç olmamasındansa aşağıdaki gibi tek satır birşey olmasını tercih ederim.(hiç yoktan iyidir)
Son olarak güzel readme kullanımlarını merak ediyorsanız.Github’ta bol yıldızlı depolara bakmanızı tavsiye ederim.