Changelog'a dönüşen feature-request-şablonu

Bir feature-request-şablonu, dört sorusu olan bir formdur: kişi ne yapmaya çalışıyor, ne onu durduruyor, bunun yerine ne denedi, ve bittiğinde nasıl bilgilendirilmek istiyor. Genellikle bir tanede görünen diğer her şey, öncelik seçiciler, çaba tahminleri, iş değeri puanları, isteği alan ekip içindir, ve onu gönderen kişi tarafından yanlış doldurulur.

Düzenli istekler bir şablon için yanlış testtir. Doğru olanı: altı ay sonra, özellik gönderildiğinde, biri isteği bulabilir mi, anlayabilir mi, ve onu yazan kişiye söyleyebilir mi? Çoğu şablon giriş için tasarlanmıştır. Bu, döngünün kapandığı gün için tasarlanmıştır.

Bir feature-request-şablonu neyi içermeli?

Amacı, engeli, geçici çözümü, ve isteyen kişiye geri dönüş yolunu içermelidir. Dört alan, bu sırayla, her biri ekibin daha sonra soracağı bir soruyu cevaplar.

Kasıtlı olarak eksik olan: zorunlu bir alan olarak önerilen bir çözüm (yorum olarak hoş geldin, çerçeve olarak yanlış), bir öncelik seçici (her gönderen yüksek seçer), ve herhangi bir çaba veya değer tahmini (triyajdan sonra ekibin işi). Bir çözüm isteyen bir şablon düğmeler için istekler alır; bir amaç isteyen bir şablon sonuçlar için istekler alır, ve sonuçlar hakkında bir changelog girdisi yazılır.

Şablon

Bu, kullandığımız GitHub issue şablonu, form olarak. Bunu .github/ISSUE_TEMPLATE/feature_request.yml içine yapıştırın ve Yeni Issue sayfasında yapılandırılmış bir form olarak görüntülenir. Onun aracılığıyla dosyalanan istekler, bir geri bildirim widget’ından dosyalananlarla aynı alanlara sahip issue’lar olarak iner, ki bu bir sonraki bölüm için önemlidir.

name: Feature request
description: What you are trying to do, and what stops you.
labels: ["feature-request"]
body:
  - type: textarea
    id: goal
    attributes:
      label: What are you trying to do?
      description: >-
        The outcome, not the button. "Export a month of invoices as one
        PDF" beats "add a PDF export".
    validations:
      required: true
  - type: textarea
    id: blocker
    attributes:
      label: What stops you today?
      description: >-
        Where the product runs out. An error, a missing option, a limit.
    validations:
      required: true
  - type: textarea
    id: workaround
    attributes:
      label: What do you do instead?
      description: >-
        The spreadsheet, the script, the manual step. "Nothing, I gave
        up" is a valid answer.
  - type: input
    id: contact
    attributes:
      label: How should we tell you when it ships?
      description: >-
        An email address, or leave blank to be notified only on this
        issue.

İki detay işi yapıyor. labels: ["feature-request"], isteğin biri triyaj edene kadar beklemek yerine oluşturulduğunda sınıflandırıldığı anlamına gelir. Ve son alan, “sana haber vereceğiz”in bir söz olduğu ve bir sözün bir adrese ihtiyacı olduğu için var.

Bir özellik isteği hangi etiketleri taşımalı?

Bir özellik isteği, ne olduğu için bir etiket, ne kadar acil olduğu için bir etiket, ve nereden geldiği için bir etiket taşımalıdır. Üç etiket, üç eksen, ve her biri farklı bir okuyucu tarafından okunur.

Widget, bir gönderimi issue olarak dosyalarken ilk iki ekseni ve from-widget’ı uygular; from-form ve from-support, başka yollardan gelen istekler için önerilerdir. Widget’ın etiketleri şunlardır: bir tür (bug veya feature-request, sadece mesajdan bir sınıflandırıcı tarafından karar verilir), bir öncelik (sakin, spesifik bir çökme raporu yüksek; zaten sorulmuş bir şeyin kopyası düşük; bir güvenlik sorununu ima eden herhangi bir şey ifade ne olursa olsun bug ve yüksek), ve from-widget. Yukarıdaki şablon aracılığıyla elle gelen istekler için de aynı üç eksen çalışır, ve bu noktadır: bir istek, nereden girmiş olursa olsun bir istektir.

Bir konvansiyon daha: widget, issue’yu dosyalamadan önce gönderenin e-posta adresini issue gövdesinden kaldırır, çünkü issue genel olabilecek bir repository’de yaşar, ve onu bir gönderim referansı ile değiştirir. Adres issue’nun dışında kalır; gönderen sonucu widget’ın kendisinde takip eder. Tracker’ınız ekip dışındaki insanlar için görünürse iletişim alanıyla aynısını yapın.

Bir özellik isteği nasıl bir changelog girdisi olur?

Bir özellik isteği, bir pull request issue’yu kapattığında ve o pull request’ten hazırlanan girdi geri bağlandığında bir changelog girdisi olur. Mekanizma, GitHub’ın kendi kapatma anahtar kelimeleridir: açıklaması Fixes #142 diyen bir PR, merge’de issue 142’yi kapatır. Changelog girdileriniz merge edilmiş pull request’lerden hazırlanıyorsa, taslak issue numarasını yanında taşıyabilir, ve girdi kimin sorduğunu bilir.

Şablonun çözüm yerine amacı sormasının nedeni budur. Girdi yazıldığında, amaç yazarın ihtiyaç duyduğu cümledir: “Artık bir aylık faturaları tek bir PDF olarak dışa aktarabilirsiniz” bir changelog girdisidir. “PDF export eklendi” bir commit mesajıdır. Pull request’lerden hazırlanan changelog araçları, toplama ve bağlantıyı yapabilir; ifade hâlâ bir insana ihtiyaç duyar, ve o insanın amaca ihtiyacı vardır.

Gönderildiğinde ne olur?

İsteyen kişiye girdiye bir bağlantıyla söylenir. Bizim kurulumumuzda bu, widget aracılığıyla gelen istekler için otomatiktir: bir insan girdiyi onayladığında issue’da yayımlanan, gönderilen girdiye bir bağlantıyla “Shipped — <girdinin başlığı>” diyen bir yorum, bu sırada widget da gönderene aynı girdiyi gösterir. Bu şablondan elle açılan bir issue otomatik yorum almaz; o döngüyü aynı kuralla kendiniz kapatın. Yorum kasıtlı olarak merge’de değil onayda yayımlanır: bir şeyin canlı olduğunu, olmadan önce söyleyen bir yorum, zaman damgalı kırık bir sözdür. Her istek en fazla bir kez bildirilir; aynı girdinin ikinci bir onayı ikinci bir yorum üretmez.

Bunu elle yapıyorsanız, aynı kural geçerlidir. Döngüyü pull request’ten kapatmayın. Onu yayımlanan girdiden kapatın, ve bir kez kapatın. Feed ve widget, aynı girdiyi sormamış olan herkese taşır, ki bu çoğu insandır; yorum sormuş olanlar içindir.

Çoğu feature-request-şablonu neden başarısız oluyor

Triyajı kolaylaştırmak için tasarlanmışlardır ve başarılı olurlar, isteyen kişi için önemli olan tek an pahasına. On iki alanlı bir şablon daha az istek alır, ve aldıkları on iki alanı doldurmak için sabra sahip insanlardan gelir, ki bu özelliğe ihtiyaç duyanlarla aynı popülasyon değildir. Biri “seninle nasıl iletişime geçelim” olan dört alanlı bir şablon daha fazla istek alır ve hepsine değer verebilir.

FAQ

Bir feature-request-şablonu öncelik sormalı mı? Hayır. Bunun yerine geçici çözümü sorun. “Bir e-tabloya export ediyorum ve her cuma yeniden giriyorum”, gönderen kişinin yüksek koyduğu bir açılır menüden daha fazlasını öncelik hakkında söyler.

İsteyenler bir çözüm önermeli mi? Serbest metinde önerebilirler. Bunu çerçeve yapmayın. Çözüm olarak yazılan istekler birbiriyle birleştirilmesi ve bir changelog girdisine dönüştürülmesi daha zordur.

Özellik istekleri genel bir roadmap’te görünmeli mi? Planlandıktan sonra, evet: aynı issue’daki bir etiket onu planlanan sütuna koyar, ve isteyen kişi nasıl hareket ettiğini görebilir. Genel roadmap makalesi mekanizmadır.

Kopyalarla nasıl başa çıkarım? Yeni isteği mevcut issue’ya bağlayın ve düşük öncelik etiketleyin; kapatmayın. Her kopya, gönderildiğinde bilgilendirilecek bir kişi daha demektir. Changeloop’un otomatik yorumuyla o kişi, ancak pull request onun issue’sunu da adlandırırsa bilgilendirilir (Fixes #142, fixes #187).

Şablon nerede yaşamalı? Pull request’i alacak repository’de, böylece kapatma anahtar kelimesi çalışır. Ayrı bir tracker’daki bir istek, merge’de elle bağlanmak zorundadır, ve atlanan adım budur.

Bu yazıdaki teknik iddialar bağımsız olarak kontrol edilmedi. Yanlış bir şey varsa bize söyle, düzeltelim.

changeloop'ta ilgili sayfalar: Geliştirici dokümantasyonu, Changelog araçları karşılaştırması