.NET belge depolarına katkıda bulunma

.NET belgelerine katkıda bulunma konusundaki ilginiz için teşekkürler!

Bu belge, .NET belgeleri sitesinde barındırılan makalelere ve kod örneklerine katkıda bulunma sürecini ele alır. Katkılarınız, yazım hatalarını düzeltmek gibi basit veya yeni bir makale oluşturmak gibi karmaşık olabilir.

.NET belge sitesi birden çok depodan oluşturulur. Bunlar yalnızca bazılarıdır:

• .NET kavramsal makaleleri ve kod parçacıkları
• Kod örnekleri ve kod parçacıkları
• .NET API başvurusu
• .NET Derleyici Platformu SDK’sı başvurusu
• ML.NET API başvurusu

Katkılara yönelik yönergeler

Belgelere topluluk katkıları için teşekkür ederiz. Aşağıdaki listede.NET belgelerine katkıda bulunurken göz önünde bulundurmanız gereken bazı kılavuz kurallar gösterilmektedir:

• YAPMAYIN: Büyük çekme istekleriyle bizi şaşırtmayın. Uzun vakitler harcamadan önce, izlemeniz gereken yol hakkında bir anlaşmaya varabilmemiz için karşılaştığınız sorunu bildirin ve bir tartışma başlatın.
• Bir makaleye satır içi örnek kod eklemeyin.
• DO , makaleye eklenecek kod içeren bir kod parçacığı projesi kullanın.
• YAPIN: Buradaki talimatları ve üslup ve ton yönergelerini izleyin.
• YAPIN: Çalışmanızın başlangıç noktası olarak şablon dosyayı kullanın.
• YAPIN: Makaleler üzerinde çalışmaya başlamadan önce çatalınızda ayrı bir dal oluşturun.
• YAPIN: GitHub akışını takip edin.
• YAPIN: İsterseniz katkılarınız hakkında blog gönderisi yazın, tweet atın veya herhangi bir şekilde haber verin!

Bu yönergeleri izleyerek hem kendiniz hem de bizim için daha iyi bir deneyim sağlarsınız.

Katkı süreci

1. Adım: Yeni içerik yazmak veya mevcut içeriği ayrıntılı bir şekilde gözden geçirmek istiyorsanız, ne yapmak istediğinizi açıklayan bir sorun açın. Docs klasörünün içindeki içerik, içindekiler tablosuna (İçindekiler tablosu) yansıtılan bölümler halinde düzenlenir. İçeriğin bu tablonun neresinde yer alacağını belirtin. Teklifiniz hakkında geri bildirim alın.

-veya-

Mevcut sorunlardan birini seçip ele alın. Açık sorunlar listemize bakıp ilginizi çeken konular üzerinde çalışmak üzere gönüllü olabilirsiniz:

• İyi ilk sorunlar için iyi ilk sorun etiketine göre filtreleyin.
• Topluluk katkısına uygun sorunlar için yardım istenen etiketine göre filtreleyin. Bu sorunlar genellikle az bağlam gerektirir.
• Deneyimli katkıda bulunanlar, ilgilerini çeken tüm sorunları ele alabilir.

Üzerinde çalışacağınız bir sorun bulursanız sorunun açık olup olmadığını sormak için bir yorum ekleyin.

Üzerinde çalışmak üzere bir görev seçtikten sonra bir GitHub hesabı oluşturun ve 2. Adım'a geçin.

2. Adım: Depoyu /dotnet/docs (veya katkıda bulunduğun depoyu) gerektiği gibi çatallayın ve değişiklikleriniz için bir dal oluşturun.

Küçük değişiklikler için bkz . Tarayıcıda düzenleme.

3. Adım: Değişiklikleri bu yeni dalda yapın.

Yeni bir konu üzerine yazıyorsanız başlangıç noktası olarak bu şablon dosyayı kullanabilirsiniz. Dosya, yazma yönergelerini içerir ve her bir makale için gerekli olan yazar bilgisi gibi meta verileri açıklar. Microsoft Learn içeriğinde kullanılan Markdown söz dizimi hakkında daha fazla bilgi için bkz . Markdown başvurusu.

1. Adımda makaleniz için belirlenen içindekiler tablosu konumuna karşılık gelen klasöre gidin. Bu klasör, bu bölümdeki tüm makalelerin Markdown dosyalarını barındırır. Gerekiyorsa içeriğinize ait dosyaları koyacağınız yeni bir klasör oluşturun. Bu bölümün ana makalesinin adı index.md’dir.

Görüntüler ve diğer statik kaynaklar için makalenizin bulunduğu klasör içerisinde medya adlı bir alt klasör yoksa yenisini oluşturun. Medya klasöründe makale adını taşıyan bir alt klasör oluşturun (dizin dosyası hariç). Dosyalarınızı nereye yerleştireceğiniz hakkında daha fazla bilgi için Örnek klasör yapısı bölümüne bakın.

Derlemeyen bir yapı göstermiyorsanız, makalede satır içi kod eklemeyin. Bunun yerine bir kod parçacıkları projesi kullanın ve kod uzantısını kullanarak kodu ekleyin. Bu, örnek kodunuzun CI sistemimiz tarafından doğrulanmasını sağlar.

Kod parçacıkları için, yoksa, makalenizi içeren klasörün içinde kod parçacıkları adlı bir alt klasör oluşturun. Kod parçacıkları klasöründe, makale adıyla yeni bir alt klasör oluşturun. Çoğu durumda, ana .NET dillerinin üçü (C#, F# ve Visual Basic) için de kod parçacıklarınız olur. Bu durumda, üç projenin her biri için csharp, fsharp ve vb adlı alt klasörler oluşturun. docs/csharp, docs/fsharp veya docs/visual-basic klasörlerindeki bir makaleye yönelik kod parçacığı oluşturuyorsanız bu kod parçacığı, dil alt klasörünü atlayabilmeniz için tek bir dilde olacaktır. Dosyalarınızı nereye yerleştireceğiniz hakkında daha fazla bilgi için Örnek klasör yapısı bölümüne bakın.

Kod parçacıkları, bir makalede ele alınan kavramları gösteren küçük ve odaklanmış kod örnekleridir. İndirme ve keşif için tasarlanan daha büyük programlar, dotnet/samples deposunda bulunmalıdır. Örneklere katkıda bulunma ile ilgili bölümde tüm örnekler ele alınmıştır.

4. Adım: Dalınızdan varsayılan dala bir çekme isteği (PR) gönderin.

Aynı çekme isteği düzeltmesi ile ilgili birden çok sorun olmadığı sürece her çekme isteği genellikle bir kerede bir sorunu çözmelidir. PR, bir veya birden fazla dosyayı değiştirebilir. Farklı dosyalardaki birden fazla düzeltmeyle ilgileniyorsanız, ayrı PR’ler göndermeniz tercih edilir.

Çekme isteğiniz mevcut bir sorunu düzeltiyorsa, anahtar sözcüğünü Fixes #Issue_Number çekme isteği açıklamasına ekleyin. Böylece PR birleştirildiğinde sorun otomatik olarak kapatılır. Daha fazla bilgi için bkz . Çekme isteğini anahtar sözcük kullanarak bir soruna bağlama.

.NET ekibi, PR’nizi inceleyecek ve PR’nin onaylanması için yapılması gereken başka güncelleştirme/değişiklik olup olmadığını size bildirecektir.

5. Adım: Ekiple konuşulduğu şekilde gerekli güncelleştirmeleri dalınıza uygulayın.

Geri bildirim uygulandıktan ve değişikliğiniz onaylandıktan sonra bakımcılar çekme isteğinizi varsayılan dalla birleştirir.

Tüm işlemeleri varsayılan daldan canlı dala düzenli olarak gönderiyoruz ve daha sonra katkınızı .NET belgelerinde canlı olarak görebilirsiniz. Çalışma haftalarında katkıları genellikle günlük olarak yayımlıyoruz.

Örnek klasör yapısı

docs
  /about
  /core
    /porting
      porting-overview.md
      /media
        /porting-overview
          portability_report.png
        /shared ...
      /snippets
        /porting-overview
          /csharp
            porting.csproj
            porting-overview.cs
            Program.cs
          /fsharp
            porting.fsproj
            porting-overview.fs
            Program.fs
          /vb
            porting.vbproj
            porting-overview.vb
            Program.vb
        /shared
          /csharp ...
          /fsharp ...
          /vb ...

Yukarıda gösterilen yapı, portability_report.png adlı tek bir görüntüyü ve porting-overview.md makalesinde yer alan kod parçacıklarını içeren üç kod projesini içerir.

Kod parçacıkları/paylaşılan klasör, önceki örnekteki taşıma klasörü gibi aynı üst klasör içindeki birden çok makaleye yayılabilen kod parçacıkları için kullanılır. Paylaşılan klasörü yalnızca, birden çok makale tarafından başvurulan ancak makaleye özgü klasörde derlenemiyor XAML kodu gibi belirli bir nedeniniz olduğunda kullanın.

Medya, bu makaleler önceki örnekteki taşıma klasörü gibi aynı üst klasörde olduğunda da makalelerde paylaşılabilir. Bu paylaşılan klasör mümkünse önlenmelidir ve yalnızca mantıklı olduğunda kullanılmalıdır. Örneğin, gösterilmekte olan uygulama için ortak bir yükleme ekranı paylaşmak veya birden çok makale arasında yeniden kullanılan Visual Studio iletişim kutularını paylaşmak mantıklı olabilir.

Örneklere katkıda bulunma

İçeriğimizi destekleyen kodlar için şu ayrımı yaparız:

• Örnekler: Okuyucular örnekleri indirebilir ve çalıştırabilir. Örneklerin tümü, tam uygulamalar veya kitaplıklar olmalıdır. Örnek, bir kitaplık oluşturuyorsa bu kitaplık, birim testleri veya okuyucuların kodu çalıştırmasını sağlayan bir uygulama içermelidir. Okuyucular genellikle birden fazla teknoloji, özellik veya araç seti kullanır. Her bir örneğin readme.md dosyası, makaleye başvurmalıdır, böylece örneklerde geçen kavramlar hakkında daha fazla şey okuyabilirsiniz.
• Kod parçacıkları: Daha küçük bir kavramı veya görevi betimler. Bunlar derlenebilir, ancak tam uygulamalar olmaları beklenmez. Düzgün çalışabilirler, ancak tipik bir senaryo için örnek uygulama değildirler. Bunun yerine, tek bir kavramı veya özelliği gösterecek kadar küçük tasarlanmıştır. Kod parçacıkları tek kodluk bir ekrandan büyük olmamalıdır.

Örnekler, dotnet/samples deposunda depolanır. Örnekler klasörünün yapısının belgeler klasörünün yapısıyla eşleştiği bir model üzerinde çalışıyoruz. İzlediğimiz standartlar şunlardır:

• Üst düzey klasörler, belgeler deposundaki üst düzey klasörlerle eşleşir. Örneğin belgeler deposunda bir machine-learning/tutorials klasörü varsa makine öğrenimi öğreticileri samples/machine-learning/tutorials klasöründedir.

Ayrıca temel ve standart klasörlerindeki tüm örnekler, .NET Core tarafından desteklenen tüm platformlarda derlenmeli ve çalışmalıdır. CI derleme sistemimiz bunu zorunlu kılar. Üst düzey çerçeve klasörü, yalnızca Windows’ta derlenen ve doğrulanan örnekleri barındırır.

Herhangi bir örnek için örnek projeler, mümkün olan en geniş platformlar kümesinde derlenmeli ve çalışmalıdır. Pratikte bu, mümkünse .NET Core tabanlı konsol uygulamaları derlemek anlamına gelir. Web’e veya bir kullanıcı arabirimi çerçevesine özgü olan örneklerde bu araçlar gerektiği gibi eklenmelidir. Web uygulamaları, mobil uygulamalar, WPF veya WinForms uygulamaları gibi öğeler örnekleri oluşturur.

Tüm kodlar için bir CI sistemi oluşturmaya yönelik olarak çalışıyoruz. Örnekleri güncelleştirdiğinizde, her bir güncelleştirmenin derlenebilir bir projenin parçası olduğundan emin olun. Örneklere doğruluk testleri eklenmesi idealdir.

Oluşturduğunuz her bir tam örnekte bir readme.md dosyası olmalıdır. Bu dosya, örneğin kısa bir açıklamasını içermelidir (bir veya iki paragraf). readme.md dosyanız, okuyuculara bu örneği keşfederek ne öğreneceklerini anlatmalıdır. readme.md dosyası ayrıca .NET belgeleri sitesindeki yayımlanmış belgeye yönlendiren bir bağlantı da içermelidir. Depodaki herhangi bir dosyanın bu siteyle eşlenip eşlenmediğini belirlemek için depo yolundaki /docs öğesini https://learn.microsoft.com/dotnet ile değiştirin.

Konunuzun içinde de örneğe yönlendiren bağlantılar olacaktır. Doğrudan örneğin GitHub’daki klasörüne bağlantı verin.

Yeni örnek yazma

Örnekler, indirilmek üzere tasarlanmış tam programlar ve kitaplıklardır. Kapsamları küçük olabilir, ancak insanların kendi başına keşfedip deneyim kazanmasına olanak sağlayacak şekilde kavramları gösterir. Örneklere yönelik yönergeler, okuyucuların indirip keşfetmesine olanak sağlar. Her bir yönergenin örneği olarak Paralel LINQ (PLINQ) örneklerini inceleyin.

1. Örneğinizin derlenebilir bir projenin parçası olması gerekir. Mümkünse projeler, .NET Core tarafından desteklenen tüm platformlarda derlenmelidir. Platforma özgü bir özellik veya platforma özgü bir araç gösteren örnekler özel durumlardır.

2. Tutarlılığı korumak için örneğiniz çalışma zamanı kodlama stiline uygun olmalıdır.

   Ayrıca, yeni bir nesne örneği oluşturmaya gerek olmayan bir şeyi gösterirken örnek metotların yerine static metotlarının kullanılmasını tercih ediyoruz.

3. Örneğinizde uygun özel durum işlemeleri olmalıdır. Örneğiniz, örnek bağlamında oluşabilecek tüm özel durumları işleyebilmelidir. Örneğin, kullanıcı girişini almak için Console.ReadLine yöntemine çağrı yapan bir örnek, giriş dizesi bir metoda bağımsız değişken olarak geçirildiğinde uygun özel durum işlemesini kullanmalıdır. Benzer şekilde, örneğiniz bir metot çağrısının başarısız olmasını bekliyorsa sonuçta ortaya çıkan özel durum işlenmelidir. Her zaman, Exception veya SystemException gibi temel sınıf özel durumlar yerine metot tarafından oluşturulan belirli özel durumları işleyin.

Örnek oluşturmak için:

1. Sorun bildirin veya mevcut bir soruna üzerine çalıştığınıza dair bir yorum ekleyin.

2. Örneğinizde gösterilen kavramları açıklayan konuyu yazın (örneğin: docs/standard/linq/where-clause.md).

3. Örneğinizi yazın (örneğin: WhereClause-Sample1.cs).

4. Örneklerinize çağrı yapan bir Ana giriş noktası içeren bir Program.cs oluşturun. Bu zaten varsa çağrıyı örneğinize ekleyin:

   public class Program
   {
       public void Main(string[] args)
       {
           WhereClause1.QuerySyntaxExample();
   
           // Add the method syntax as an example.
           WhereClause1.MethodSyntaxExample();
       }
   }
   

.NET SDK'sı ile yüklenebilen .NET CLI kullanarak herhangi bir .NET kod parçacığı veya örneği oluşturursunuz. Örneğinizi derlemek ve çalıştırmak için:

1. Örnek klasörüne ve derlemesine giderek hataları denetleyin:

   dotnet build
   

2. Örneğinizi çalıştırın:

   dotnet run
   

3. Örneğinizin kök dizinine bir readme.md dosyası ekleyin.

   Bu dosya, kodun kısa açıklamasını içermeli ve kişileri örneğe başvuran makaleye yönlendirmelidir. Readme.md dosyasının üst kısmında, örnekler tarayıcısı için gerekli meta veriler yer almalıdır. Üst bilgi bloğu şu alanları içermelidir:

   ---
   name: "really cool sample"
   description: "Learn everything about this really cool sample."
   page_type: sample
   languages:
     - csharp
     - fsharp
     - vbnet
   products:
     - dotnet-core
     - dotnet
     - dotnet-standard
     - aspnet
     - aspnet-core
     - ef-core
   ---
   

   • languages koleksiyonu yalnızca örneğiniz için kullanılabilen dilleri içermelidir.
   • products koleksiyonu yalnızca örneğinizle ilgili ürünleri içermelidir.

Belirtilen durumlar dışında, tüm örnekler .NET tarafından desteklenen herhangi bir platformda komut satırından derlenmiştir. Visual Studio’ya özgü olan ve Visual Studio 2017 veya üzerini gerektiren bazı örnekler vardır. Ayrıca bazı örnekler, platforma özgü özellikler gösterir ve belirli bir platform gerektirir. Diğer örnekler ve kod parçacıkları .NET Framework gerektirir ve Windows platformlarında çalışır. Bunlar hedef Framework sürümü için Geliştirici Paketi’ni gerektirir.

Etkileşimli C# deneyimi

Bir makaledeki tüm kod parçacıkları, kaynak dili belirtmek için bir dil etiketi kullanır. C# dilindeki kısa kod parçacıkları, tarayıcıda çalışan bir C# kod parçacığı belirtmek için dil etiketini kullanabilir csharp-interactive . (Satır içi kod parçacıkları etiketini kullanır csharp-interactive , kaynaktan gelen kod parçacıkları için etiketini kullanın code-csharp-interactive .) Bu kod parçacıkları makalede bir kod penceresi ve bir çıkış penceresi görüntüler. Çıkış penceresinde , kullanıcı kod parçacığını çalıştırdıktan sonra etkileşimli kodun yürütülmesinden elde edilir.

C# etkileşimli deneyimi kod parçacıklarıyla çalışma şeklimizi değiştirir. Ziyaretçiler sonuçları görmek için kod parçacığını çalıştırabilir. Kod parçacığının veya buna karşılık gelen metnin çıktı hakkında bilgi içermesi gerekip gerekmediğini belirlemeye yardımcı olan bir dizi faktör vardır.

Kod parçacığı çalıştırılmadan beklenen çıkışın ne zaman görüntüleneceği

• Yeni başlayanlara yönelik makaleler, okuyucunun kendi sonuçlarıyla beklenen yanıtı kıyaslayabilmesi için çıkış sağlamalıdır.
• Çıkışın konu başlığının ayrılmaz olduğu kod parçacıklarında bu çıkış görüntülenmelidir. Örneğin, biçimlendirilmiş metinle ilgili makalelerde kod parçacığı çalıştırılmadan metin biçimi gösterilmelidir.
• Hem kod parçacığı hem de beklenen çıkış kısa olduğunda, çıkışı göstermeyi göz önünde bulundurun. Bu, bir miktar zaman tasarrufu sağlar.
• Geçerli kültür veya sabit kültürün çıkışı nasıl etkilediğini açıklayan makalelerde beklenen çıkış açıklanmalıdır. Etkileşimli REPL (Oku Değerlendir Yazdır Döngüsü), Linux tabanlı bir ana bilgisayarda çalışır. Varsayılan kültür ve sabit kültür, farklı işletim sistemlerinde ve makinelerde farklı sonuçlar üretir. Bu makalede Windows, Linux ve Mac sistemlerindeki çıkış açıklanmıştır.

Beklenen çıkışın kod parçacığından ne zaman dışlanması gerekir?

• Kod parçacığının daha büyük bir çıkış oluşturduğu makaleler, açıklamalarda bunu içermemelidir. Kod parçacığı çalıştırıldıktan sonra kodu gizler.
• Kod parçacığının bir konuyu gösterdiği, ancak çıkışın bunu anlamanın ayrılmaz bir parçası olmadığı makaleler. Örneğin, sorgu söz dizimini açıklamak için bir LINQ sorgusu çalıştıran ve daha sonra tüm öğeleri çıkış koleksiyonunda görüntüleyen kodlar.

İngilizce olmayan içeriğe katkıda bulunma

Şu anda Makine Tarafından Çevrilmiş (MT) içeriklere yönelik katkılar kabul edilmiyor. MT içeriğinin kalitesini iyileştirme amacıyla Nöral MT altyapısına geçiş yaptık. Nöral MT altyapısını eğitmek için kullanılacak olan İnsan Tarafından Çevrilmiş (HT) içeriğe yönelik katkıları kabul ve teşvik ediyoruz. Yani, HT içeriğine yapılan katkılar zaman içinde hem HT’nin hem de MT’nin kalitesini iyileştirecektir. MT konularında, konunun bir parçasının MT olabileceğini ve düzenleme devre dışı bırakıldığından Düzenle düğmesinin görüntülenmeyeceğini belirten bir sorumluluk reddi yer alır.

Katkıda bulunan lisans sözleşmesi

PR’niz birleştirilmeden önce .NET Foundation Katılım Lisans Sözleşmesi’ni (CLA) imzalamanız gerekir. Bu, .NET Foundation projeleri için tek seferlik bir gereksinimdir. Katılım Lisans Sözleşmeleri (CLA) hakkında Wikipedia’dan daha fazla bilgi edinebilirsiniz.

Sözleşme: .NET Foundation Katılımcı Lisans Sözleşmesi (CLA)

Sözleşmeyi önceden imzalamanız gerekmez. PR’nizin kopyalama, gönderme, çatalını oluşturma işlemlerini her zamanki gibi yapabilirsiniz. PR’niz oluşturulduğunda, bir CLA botu tarafından sınıflandırılır. Değişiklik büyük değilse (örneğin bir yazım hatasını düzelttiyseniz) PR cla-not-required olarak etiketlenir. Büyük değişikliklerde ise cla-required olarak sınıflandırılır. CLA’yı imzaladıktan sonra geçerli ve gelecek tüm çekme istekleri cla-signed olarak etiketlenir.