Proje rehberleri

Açık kaynak bir proje için GitHub README şablonu

Yararlı bir GitHub README dosyası dört soruyu hızla yanıtlar: Bu proje ne yapar, kimler içindir, nasıl denerim ve nereden yardım alırım? Aşağıdaki Markdown şablonunu başlangıç olarak kullanın, ardından her yer tutucuyu projenizle karşılaştırıp doğruladığınız bilgilerle değiştirin.

GitHubStart yayın ekibi · Güncellendi

Bu Markdown README şablonunu kopyalayın

Bu, hazırlanmış bir başlangıç şablonudur; çalışan bir yazılım örneği değildir. Köşeli parantez içindeki metni değiştirin, atıf yapılan dosyaların varlığını kontrol edin ve geçersiz bölümleri kaldırın. Aşağıdaki kurulum ve çalıştırma satırları, yer tutucu komutların yanlışlıkla yürütülmemesi için yorum olarak yazılmıştır.

# [Proje adı]

[Tek cümle: sorun, hedef kullanıcı ve sonuç.]

## Örnek
[Küçük bir girdi ve beklenen çıktısını gösterin veya ekran görüntüsü ekleyin.]

## Hızlı başlangıç
Gereksinimler: [çalışma zamanı/sürüm ve gerekli hizmetler].

```sh
# Doğruladığınız kurulum komutuyla değiştirin.
# Yararlı bir sonuç üreten en küçük komutla değiştirin.
```

Beklenen sonuç: [okuyucunun görmesi gereken şey].

## Yapılandırma
[Zorunlu ayarlar, güvenli örnek değerler ve gizli bilgilerin saklanacağı yer.]

## Ne zaman kullanılır?
- [Somut bir kullanım senaryosu]
- [İkinci bir kullanım senaryosu]

## Kısıtlamalar
[Desteklenmeyen girdiler, olgunluk, performans veya platform sınırları.]

## Belgeler ve yardım
[Belgelere bağlantı verin ve nerede soru sorulacağını açıklayın.]

## Katkıda bulunma
Bkz. [CONTRIBUTING.md](CONTRIBUTING.md).
Yeniden üretilebilir sorunları deponun Issues sekmesinden bildirin.

## Lisans
Bkz. [LICENSE](LICENSE).

Örneği depo türüne uyarlayın

Komut satırı aracı için bir girdi dosyası, komut ve kısa çıktı gösterin. Kütüphane için beklenen dönüş değeri dâhil, en küçük eksiksiz içe aktarma ve çağırma örneğini gösterin. Web uygulaması için ana iş akışını gösterin ve barındırılan demo veya yerel kurulum bulunup bulunmadığını açıklayın.

API'yi yalnızca ekran görüntüsüyle açıklamaktan kaçının: okuyucular kodu kopyalayabilmelidir. Buna karşılık görsel bir uygulama, kullanıcının ne yaptığını açıkça anlatan bir ekran görüntüsünden yararlanabilir. Şu anda dağıttığınız sürümden gerçek örnekler kullanın.

  • Kütüphane: kurulum, desteklenen çalışma zamanı ve eksiksiz bir fonksiyon çağrısı.
  • CLI: girdi, komut, çıktı ve hataların nasıl bildirildiği.
  • Web uygulaması: demo bağlantısı veya yerel kurulum, yapılandırma ve ana görevin ekran görüntüsü.
  • Veri kümesi: kaynak, biçim, lisans ve küçük bir örnek kayıt.

Paylaşmadan önce README dosyasını kontrol edin

Hızlı başlangıcı, geliştirme için zaten yapılandırılmış makine yerine temiz bir ortamda deneyin. Belirtilmemiş bir genel paket, özel paket kayıt deposu veya yerel dosya gerekip gerekmediğini kontrol edin. Kurulum hesap veya ücretli hizmet gerektiriyorsa bunu ilk komuttan önce söyleyin.

Depo sayfasından belge ve görsel bağlantılarını açın. Katkı ve lisans dosya adlarının deponuzla eşleştiğini doğrulayın, bozuk bağlantıları kaldırın. Kısa ve doğru bir README, henüz uygulamadığınız vaatlerle dolu etkileyici görünümlü şablondan daha iyidir.

  • Yer tutucuları ve dayanağı olmayan iddiaları kaldırın.
  • Örneklerde gerçek token, parola ve özel URL kullanmayın.
  • Beklenen çıktının yayımlanan sürümle eşleştiğini kontrol edin.
  • Sorun bildirirken hangi bilgilerin gerekli olduğunu okuyuculara söyleyin.

README dosyasını lansman özetiniz olarak kullanın

Şablonu tamamladıktan sonra kısa bir tanıtım çıkarın: sorun hakkında bir cümle, sonuca bir örnek ve denemek için bir bağlantı. Bu, topluluk paylaşımının başlangıcı olur. Özgün README dosyasını ayrıntılı kaynak olarak koruyun; her yerde aynı tanıtım paragrafını tekrarlamak yerine her girişi okuyucuya uyarlayın.

Sık sorulan sorular

Bu bir depo README'si mi, profil README'si mi?

Bu şablon bir yazılım deposu içindir. Profil README'si bir kişiyi tanıtır ve çalışmaları ile iletişim tercihleri gibi farklı bölümler gerektirir.

Üste yıldız rozetleri eklemeli miyim?

Yalnızca okuyucuya yardımcı oluyorsa. Amacı ve hızlı başlangıcı görünür tutun. Rozet, projenin ne yaptığını açıklamanın yerini tutmaz.

Bu şablonu özel bir proje için kullanabilir miyim?

Evet. Herkese açık destek bağlantılarını ekibinizin gerçek yardım kanallarıyla değiştirin, erişim gereksinimlerini açıklayın ve kimlik bilgilerini belgeye koymayın.

Kaynaklar