Deponuz için README dosyası oluşturma

  • Makale

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

Git deponuzda, görüntüleyenlerin kodunuzun ne yaptığını ve kullanmaya nasıl başlayabileceğinizi bilmesi için bir benioku dosyası olmalıdır. Beniokunuzun aşağıdaki hedef kitlelerle konuşması gerekir:

  • 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'a yazın. Markdown, metni biçimlendirmeyi, görüntüleri eklemeyi ve gerektiğinde benioku bilginizden daha fazla belgeye bağlanmayı kolaylaştırır.

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

Giriş oluşturma

Projenizi açıklayan kısa bir açıklamayla benioku ile 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

Beniokunuzun bir sonraki bölümünde kodunuzu kendi sistemleri üzerinde çalıştırma konusunda kullanıcılara yol gösterebilirsiniz. Kodunuzu kullanmaya başlamak için temel 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, beniokunuzun 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ığı koyun 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 beniokunuzun sonraki bölümünü kullanın. Aşağıdakileri 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, yönergelerin yeni bir katkıda bulunan için işe yarayacağını doğrulamak için yönergeleri gözden geçirin.

Unutmayın, bu yönergelere güvenen geliştirici, bir süre bir 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 sorunları bildirmelerine 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 topluluk kullanım kurallarını uygulamak için katkıda bulunan sözleşmesine ihtiyacınız varsa, bu süreç bu bölüme bağlanmalıdır veya belgelenmelidir. Kodun hangi lisansın altında yayımlanıp lisans metninin tamamının bağlantısını belirtin.