Deponuz için BENİOKU oluşturma

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018

İzleyicilerin kodunuzun ne yaptığını ve kullanmaya nasıl başlayabileceğinizi bilmesi için Git deponuzun bir benioku dosyası olmalıdır. Benioku bilginiz aşağıdaki izleyicilerle konuşmalıdır:

  • Yalnızca kodunuzu çalıştırmak isteyen kullanıcılar.
  • Kodunuzu derlemek ve test etmek isteyen geliştiriciler. Geliştiriciler de kullanıcıdır.
  • Kodunuzda değişiklik göndermek isteyen katkıda bulunanlar. Katkıda bulunanlar hem geliştiriciler hem de kullanıcılardır.

Benioku dosyanızı düz metin yerine Markdown'da yazın. Markdown metin biçimlendirmeyi, resim eklemeyi ve gerektiğinde benioku bilginizden daha fazla belgeye bağlantı sağlamayı kolaylaştırır.

Bu biçimi kullanan ve referans ve ilham almak için üç hedef kitleyle de konuşan bazı harika beniokular aşağıdadır:

Giriş oluşturma

Projenizi açıklayan kısa bir açıklamayla benioku okumaya başlayın. Projenizin kullanıcı arabirimi varsa, girişinize bir ekran görüntüsü veya animasyonlu GIF ekleyin. Kodunuz başka bir uygulama veya kitaplığa bağımlıysa, bu bağımlılıkları girişte veya hemen altında belirttiğinizden emin olun. Yalnızca belirli platformlarda çalışan uygulamalar ve araçlar, benioku'nun bu bölümünde belirtilen desteklenen işletim sistemi sürümlerine sahip olmalıdır.

Kullanıcılarınızın kullanmaya başlamasına yardımcı olun

Benioku dosyasının sonraki bölümünde kodunuzun kendi sisteminde çalışır duruma geçmesi için kullanıcılara yol gösterebilirsiniz. Kodunuzu kullanmaya başlamak için gerekli adımlara odaklanın. Kullanıcıların bunlara kolayca ulaşabilmesi için herhangi bir önkoşul yazılımının gerekli sürümlerine bağlanın. Karmaşık kurulum adımlarınız varsa, benioku dışındakileri belgeleyin ve bunlara bağlantı sağlayın.

Kodunuzun en son sürümünü nereden edineceğinize dikkat edin. İkili yükleyici veya kodunuzu paketleme araçlarıyla kullanma yönergeleri en iyisidir. Projeniz bir kitaplık veya API arabirimiyse, temel kullanımı gösteren bir kod parçacığı yerleştirin ve kod parçacığındaki kod için örnek çıktıyı gösterin.

Geliştiriciler için derleme adımları sağlama

Geliştiricilere deponun yeni bir kopyasından kodunuzu nasıl oluşturacaklarını ve dahil edilen testleri nasıl çalıştıracaklarını göstermek için benioku'nuzun sonraki bölümünü kullanın. Şunları yapın:

  • Kodu derlemek için gereken araçlar hakkında ayrıntılı bilgi verin ve bunları temiz bir derleme elde etmek üzere yapılandırma adımlarını belgeleyin.
  • Yoğun veya karmaşık derleme yönergelerini belgelerinizde ayrı bir sayfaya ayırın ve gerekirse bu sayfaya bağlanın.
  • Yönergeleri yazarken gözden geçirerek yönergelerin yeni bir katkıda bulunan için işe yarayacağını doğrulayın.

Unutmayın, bu yönergeleri kullanan geliştirici bir süre proje üzerinde çalışmadıktan sonra siz olabilirsiniz.

Derleme başarılı olduktan sonra kaynak koduyla sağlanan test çalışmalarını çalıştırmak için komutları sağlayın. Geliştiriciler, değişiklik yaparken kodunuzu bozmadığından emin olmak için bu test çalışmalarını kullanır. İyi test çalışmaları, geliştiricilerin yeni işlevler eklerken kendi test çalışmalarını oluşturmak için kullanabileceği örnekler olarak da görev yapar.

Kullanıcıların katkıda bulunmalarını sağlama

Benioku dosyasının son bölümü, kullanıcıların ve geliştiricilerin raporlama sorunlarına katılmalarına ve kodunuzu daha iyi hale getirmek için fikirler önermelerine yardımcı olur. Kullanıcılar hataları açabilecekleri, özellik isteyebilecekleri veya kodunuzu kullanarak yardım alabilecekleri kanallara bağlanmalıdır.

Geliştiricilerin, kodlama/test yönergeleri ve çekme isteği gereksinimleri gibi değişikliklere katkıda bulunmak için izlemeleri gereken kuralları bilmeleri gerekir. Çekme isteklerini kabul etmek veya bir topluluk kullanım kodunu zorunlu kılmak için katkıda bulunan sözleşmesine ihtiyacınız varsa, bu işlem bu bölüme bağlanmalıdır veya belgelenmelidir. Kodun hangi lisansta yayımlanıp lisansın tam metnine bağlanıldığını belirtin.