Aracılığıyla paylaş

Kalite geliştirmelerine katkıda bulunma

Hacktoberfest 2022 için PowerShell içeriğinde kalite iyileştirmelerine katkıda bulunmaya yönelik bir sürecin pilotunu yaptık. Bu kılavuz, topluluk üyelerinin belge kalitesini iyileştirmesi için düşük sürtüşmeli bir yol tanımlama sürecini genelleştirir.

Şu kalite alanlarına odaklanıyoruz:

Proje İzleme

PowerShell Docs Kalite Katkıları GitHub Projesi ile katkıları izliyoruz.

Proje sayfasında bu çalışmayla ilgili sorunlar ve PR'ler için çeşitli görünümler bulunur:

Kod örneklerini biçimlendirme

Tüm kod örnekleri PowerShell içeriği için stil yönergelerini izlemelidir. Bu kurallar, kolaylık sağlamak için burada kısaltılmış biçimde yinelenir:

  • Tüm kod blokları üç tane arka arkaya ters tırnak işaretiyle oluşturulmuş bir kod çitinde (```) bulunmalıdır.
  • Kod blokları için satır uzunluğu, cmdlet başvuru makalelerinin karakterleriyle 90 sınırlıdır.
  • Kod blokları için satır uzunluğu, 76 karakterle about_* makaleler için sınırlıdır.
  • PowerShell kod örneklerinde satır devamlılığı karakterlerini (`) kullanmaktan kaçının.
    • Çizgi uzunluğunu sınırlamak için pipe (|) karakterlerinden, açma ayraçlarından (}), parantezlerden (() ve köşeli ayraçlardan ([) sonra yapılan kod bölme veya doğal satır kesme fırsatlarını kullanın.
  • Görsel örneklerde, kodun kopyala-yapıştır amacıyla kullanılmadığı durumlarda yalnızca PowerShell istemini ekleyin.
  • Özellikle takma adı belgelemediğiniz sürece örneklerde takma adları kullanmayın.
  • Konumsal parametreleri kullanmaktan kaçının. Parametre konumsal olsa bile parametre adını kullanın.

Biçimlendirme komutunun söz dizimi

Tüm düz yazılar PowerShell içeriği için stil yönergelerini izlemelidir. Bu kurallar kolaylık sağlamak için burada yinelenir:

  • Cmdlet'ler ve parametreler için her zaman tam adı kullanın. Özellikle bir takma adı göstermediğiniz sürece takma ad kullanmaktan kaçının.
  • Özellik, parametre, nesne, tür adları, sınıf adları, sınıf yöntemleri kalın olmalıdır.
    • Özellik ve parametre değerleri ters tırnak işareti (`) içinde sarmalanmalıdır.
    • Köşeli ayraçlı stili kullanarak türlere başvururken, arka uçları kullanın. Örneğin: [System.Io.FileInfo]
  • PowerShell modülü adları kalın olmalıdır.
  • PowerShell anahtar sözcüklerinin ve işleçlerinin tümü küçük harf olmalıdır.
  • Cmdlet adları ve parametreler için uygun (Pascal) büyük/küçük harf kasası kullanın.
  • Parametreye adıyla başvurduğunuzda, ad kalın olmalıdır.
  • Söz dizimini gösterirken parametre adını kısa çizgiyle birlikte kullanın. parametresini ters köşelere sarmalar.
  • Bir dış komutun örnek kullanımını gösterdiğinizde, örnek ters köşelerde sarmalanmalıdır. Her zaman dış komutun dosya uzantısını ekleyin.

Belgelerimizin markdown kaynağının sürdürülebilirliği ve okunabilirliği için kavramsal belgelerimizi satır içi bağlantılar yerine bağlantı başvurularını kullanacak şekilde dönüştürüyoruz.

Örneğin, yerine:

The [Packages tab][31] displays all available
packages in the PowerShell Gallery.

Şu şekilde olmalıdır:

The [Packages tab][31] displays all available packages in the PowerShell Gallery.

Uyarı

Satır içi bağlantıyı değiştirdiğinizde, içeriği 100 karakter sınırında saracak şekilde yeniden düzenleyin. Paragrafı hızla yeniden akıtmak için reflow-markdown VS Code uzantısını kullanabilirsiniz.

Dosyanın en altına bağlantıların tanımından önce bir markdown açıklaması ekleyin.

<!-- Link references -->
[01]: https://www.powershellgallery.com/packages

Şunlardan emin olun:

  1. Bağlantılar, belgede göründükleri sırayla tanımlanır.
  2. Her bağlantı doğru konumu gösterir.
  3. Bağlantı başvurusu tanımları, markdown açıklamasından sonra dosyanın en altındadır ve doğru sıradadır.

Markdown kod denetimi

Katılımcı depolardan birinde yer alan herhangi bir makale için makaleyi VS Code'da açtığınızda linting uyarıları gösterilir. Aşağıdakiler dışında bulduğunuz bu uyarılardan herhangi birini ele alın:

Satır uzunluklarından emin olun ve uzun çizgileri düzeltmek için Reflow Markdown uzantısını kullanın.

Yazım

Tüm çabalarımıza rağmen, yazım hataları belgelere sızar ve orada yer alır. Bu hatalar, belgelerin takip ve yerelleştirilmesini zorlaştırır. Bu hataları düzeltmek, özellikle doğru çevirilere güvenen İngilizce olmayan konuşmacılar için belgelerin daha okunabilir olmasını sağlar.

İşlem

İyileştirmek için bir veya daha fazla kalite alanı ve makale (veya makale grubu) seçmenizi öneririz. Çalışmanıza yol göstermek için aşağıdaki adımları kullanın:

  1. Yinelenen çabaları önlemek için, bu girişimle ilgili olarak proje üzerinde dosyalanan sorunları kontrol edin.

  2. Uygun depoda yeni bir konu açın.

  3. Değişikliklerinizi yapmaya hazırlanmak için katkıda bulunan rehberimizi izleyin.

  4. Çekme talebinizi gönderin. Sağlamak:

    1. Çekme isteği başlığınızda Quality: ön eki bulunuyor.

    2. PR açıklaması, çözümlenen soruna sıralı olmayan bir liste öğesi olarak referans verir ve bağlama anahtar sözcüklerinden birini kullanır.

      Örneğin, sorun 123 üzerinde çalışıyorsanız, pull isteğinizin gövdesi aşağıdaki Markdown formatını içermelidir:

      - resolves #123

    PR'yi gönderdikten sonra geliştirici ekibi çalışmanızı gözden geçirir ve birleştirip değerlendirmek için sizinle çalışır.

  • Last updated on