Aracılığıyla paylaş


Depo için bir README dosyası oluşturun

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

Git deponuzda, görüntüleyenlerin kodunuzun ne yaptığını ve onu kullanmaya nasıl başlayabileceklerini bilmeleri için bir benioku dosyası olmalıdır. Readme'nizin aşağıdaki hedef kitlelere hitap etmesi 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 Markdown düz metin yerine yazın. Markdown, metni biçimlendirmeyi, görüntüleri eklemeyi ve gerektiğinde readme dosyanızdan daha fazla belgeye bağlantı vermeyi kolaylaştırır.

Referans ve ilham almak için bu biçimi kullanan ve üç farklı hedef kitleye hitap eden bazı harika "readme" dosyaları aşağıdadır:

Önkoşullar

Kategori Gereksinimler
Proje erişimi projesiüyesi.
İzinler - Özel projelerde kodu görüntüleme: En az Temel erişimi.
- Özel projelerde kodu klonlama veya katkıda bulunma: Projede Katkıda Bulunanlar güvenlik grubuna üyelik veya ilgili izinler.
- Dal veya depo izinlerini ayarlayın: izinleri yönetin dal veya depo için.
- Varsayılan dalı değiştirme: Depo için izinleri ilkeleri düzenleyin.
- Depoyu içeri aktarma: Proje Yöneticileri güvenlik grubunun üyesi veya Git proje düzeyi Depo oluşturma izni İzin verolarak ayarlanmıştır. Daha fazla bilgi için bkz . Git deposu izinlerini ayarlama.
Hizmetler Repo'lar etkinleştirildi.
Araçlar Opsiyonel. az repos komutlarını kullanın: Azure DevOps CLI.

Uyarı

Genel projelerde, Paydaş erişimi olan kullanıcılar, kod görüntüleme, kopyalama ve koda katkıda bulunma dahil olmak üzere Azure Depolarına tam erişime sahiptir.

Kategori Gereksinimler
Proje erişimi projesiüyesi.
İzinler - Kodu görüntüle: En az Temel erişim.
- Kodun bir kopyasını oluşturma veya koda katkıda bulunma: Katkıda Bulunanlar güvenlik grubunun üyesi veya projedeki ilgili izinlere sahip olma.
Hizmetler Depo etkinleştirildi.

Giriş oluşturma

Benioku dosyanıza projenizi açıklayan kısa bir açıklamayla 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

Readme dosyanızın bir sonraki bölümünde, kullanıcıları kodunuzu kendi sistemlerinde çalıştırma konusunda yönlendirin. 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, README dosyanızın dışındaki bu adımları dokümante edin ve onlara bağlantı verin.

Kodunuzun en son sürümünü nereden edineceğinize dikkat edin. İkili bir yükleyici veya kodunuzu paketleme araçlarıyla kullanma talimatları 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ştiricilere derleme adımlarını sağlayın

Readme dosyanızın bir sonraki bölümünü, geliştiricilere deponun yeni bir kopyasından kodunuzu nasıl oluşturabileceklerini ve dahil edilen testleri nasıl çalıştırabileceklerini anlatmak için 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.
  • Belgelerinizdeki yoğun veya karmaşık derleme yönergelerini ayrı bir sayfada toplayın ve gerekirse o sayfaya bağlantı verin.
  • 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

Readme dosyanızın son bölümü, kullanıcıların ve geliştiricilerin sorunları bildirmesine ve kodunuzu daha iyi hale getirmek için fikirler önermesine olanak tanır. 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.