Hata düzeltmesi release notes: işe yarayan girdiler yazmak

İyi hata düzeltmesi release notes, kodun neyi yanlış yaptığını değil kullanıcının neyin ters gittiğini gördüğünü anlatır. Her girdi kimin etkilendiğini, ne zamandan beri olduğunu, düzeltmenin tam olup olmadığını ve okuyucunun bir şey yapması gerekip gerekmediğini söyler, bu sadece “hiçbir işlem gerekmiyor” olsa bile.

Çoğu ekip commit mesajından bir satır kopyalar. Tablo altı yeniden yazımı gösteriyor, sonraki bölümler kuralları açıklıyor.

Release notes’ta bir hata düzeltmesi girdisi nasıl yazılır?

Kullanıcının kendi kelimeleriyle belirtiyle başlayın, sonra kimin etkilendiğini ve ne zamandan beri olduğunu, sonra düzeltmenin durumunu, sonra eylemi yazın. Bir ya da iki cümle genellikle yeter. Kodun nedeni, bir mühendisin bakacağı yer olan pull request’e aittir.

Okuyucu tek bir şey için tarar: “Bu ben miydim?” Dört parça hemen her girdiyi kapsar:

1. Belirti. Ekranda, API yanıtında ya da faturada ne göründü. Bir hata metni varsa alıntılayın, çünkü insanlar onu arar.
2. Kapsam. Hangi plan, platform, API sürümü ya da veri biçimi. “50.000’den fazla satırı olan hesaplar” kontrol edilebilir. “Bazı kullanıcılar” edilemez.
3. Aralık. Hangi sürümden ya da tarihten beri, böylece okuyucu dünkü tuhaf sonucun hata olup olmadığına karar verebilir.
4. Eylem. Yeniden çalıştırmak, yeniden senkronize etmek, yükseltmek, bir geçici çözümü kaldırmak ya da hiçbir şey.

Kullanıcılar bir geçici çözüm kurduysa, eylem satırı onlara silebileceklerini söylediğiniz yerdir.

Release note ile changelog arasındaki fark nedir?

Changelog, değişikliklerin eksiksiz ve sürekli kaydıdır. Release notes ise önemseyip önemsemeyeceğine karar veren insanlar için tek bir sürüm hakkında seçilmiş, yeniden yazılmış mesajdır. Hata düzeltmelerinde changelog her düzeltmeyi listeler, notlar ise okuyucunun fark edebileceği olanlarla açılır.

Bir tooltip yazım hatası sadece changelog’a aittir. Faturalardaki yanlış bir vergi oranı ikisine de aittir. Tam ayrım changelog vs release notes yazısında, iyi bir not setinin şekli ise release notes nasıl yazılır yazısında.

Keep a Changelog, kayıt tarafı için kullanışlı bir gelenektir. Her hata düzeltmesi için “Fixed”, güvenlik açıkları için ayrı bir “Security” başlığı tutar; bu, bu makalenin okuyucu için yaptığı ayrımın aynısıdır.

Hata düzeltmesi bir güncelleme midir?

Evet. Hata düzeltmesi ürünü değiştirir, o yüzden birini yayımlamak bir güncellemedir. Semantic versioning altında geriye uyumlu bir düzeltme bir patch release’tir, örneğin 4.2.0’dan 4.2.1’e.

Okuyucunun bir şey yapması gerekip gerekmediği ayrı bir sorudur ve not onu cevaplamalıdır. Doğru çağıranın gözlemlediğini değiştiren bir düzeltme, breaking change’e yakındır ve breaking change’ler yazısı bu çizginin nerede durduğunu anlatır.

Bir düzeltme ne zaman kendi girdisini alır, ne zaman küçük düzeltmedir?

Bir kullanıcı hatayı fark edebildiyse, ona zaman ya da veri kaybettiyse ya da etrafında bir geçici çözüm kurduysa düzeltmeye kendi girdisini verin. Ekibinizin dışında kimsenin göremeyeceği olanları kısa bir “Küçük düzeltmeler” listesine toplayın. Diff’in boyutuna değil okuyucunun deneyimine göre karar verin.

Gruptaki her satır yine de bir şey söylemeli: “Bazı UI sorunları düzeltildi” bir yer tutucudur.

Bir regresyon hakkında nasıl yazılır?

Onu getiren release’i adlandırın, regresyon deyin ve düzelten release’i verin. Hatayı yaşayanlar zaten bozulduğunu biliyor, o yüzden kısa ve doğrudan bir kabul, belirsiz ifadeden onlara daha iyi hizmet eder.

Örneğin: “Tire içeren sorguların arama sonuçları 4.1.0’da boş geliyordu. Bu 4.1.1’de düzeltildi. Tireleri önlemek için sorgularınızı değiştirdiyseniz, geri değiştirebilirsiniz.”

“Arama güvenilirliği iyileştirildi”, hata yüzünden bir öğleden sonrasını kaybeden herkese kaçamak gibi okunur. Neden hâlâ doğrulanıyorsa bunu söyleyin; acil durum release notes rehberinin dediği gibi: notun asla ekipten daha emin ses vermesine izin vermeyin.

Güvenlik düzeltmesi nasıl duyurulur?

Ciddiyeti açıkça belirtin, etkilenen sürümleri ve onları düzelten sürümü adlandırın, yükseltmenin ne kadar acil olduğunu söyleyin ve varsa CVE tanımlayıcısını ekleyin. Ayrıntıları ancak kullanıcılar bir düzeltmeye göre harekete geçebildiğinde yayımlayın; bir bildirimde bulunan kişi varsa koordine ifşa sürecini izleyin.

Sıra önemlidir: bildiren kişi size özel olarak söyler, düzeltmeyi yayımlarsınız ve herkese açık not kullanıcılar kendilerini koruyabildiğinde çıkar. CISA’nın koordine güvenlik açığı ifşa süreci güvenlik açıklarının bildirilmesini, analizini ve kamuya açıklanmasını koordine eder. CVE Numbering Authority kuralları CVE kayıtlarının nasıl atanıp yayımlanacağını belirler ve GitHub’da bir repository security advisory, duyuruyu özel olarak taslak hâlinde hazırlamanıza ve bir tanımlayıcı istemenize olanak verir.

Bir güvenlik girdisi genellikle dört olgu taşır:

• Bir saldırganın ne yapabileceği, tek cümlede ve bir kavram kanıtı olmadan.
• Etkilenen sürümler ve onu düzelten sürüm.
• Ne kadar acil olduğu: “bugün yükseltin” ya da “bir sonraki release’inizde yükseltin”.
• İstismar görüp görmediğiniz ve bildiren kişi kabul ettiyse ona teşekkür.

İstismar adımlarını dışarıda bırakın.

Bir not, veri kaybı düzeltmesi hakkında ne söylemeli?

Hangi verinin etkilendiğini, sizinkinin etkilenip etkilenmediğinin nasıl anlaşılacağını ve kurtarılıp kurtarılamayacağını söyleyin. “Hiçbir işlem gerekmiyor” burada nadiren doğrudur ve okuyucunun ilk sorusu “verim gitti mi” olur.

Kullanışlı bir girdi, veri kaybettiren koşulu (“bir senkronizasyon çalışırken bir klasörü silmek”), bunun mümkün olduğu aralığı, bir kontrol yolunu (“Çöp Kutusu’nu açın ve 3 ile 9 Eylül tarihli öğelere bakın”) ve kurtarma yolunu verir. Veri kurtarılamıyorsa bunu söyleyin. Etkilenen müşterilerle ayrıca doğrudan iletişime geçin, çünkü release note, birinin verisinin etkilendiğini öğrendiği tek yer olmamalı.

“Hata düzeltmeleri ve performans iyileştirmeleri” neden kötü bir nottur?

Okuyucuya üzerine harekete geçecek hiçbir şey vermez ve birinin beklediği düzeltmeleri gizler. Bir çökmeyi bildiren müşteri bunun düzelip düzelmediğini anlayamaz, geçici çözümü olan müşteri de onu kaldırıp kaldırmayacağını.

İki dürüst alternatif var. Bir release’te okuyucunun fark edebileceği hiçbir şey yoksa, onun için not yayımlamayın ve kaydı changelog’a bırakın. Düzeltmeler varsa, okuyucunun diliyle listeleyin:

Önce:
  Hata düzeltmeleri ve performans iyileştirmeleri.

Sonra:
  Düzeltildi: etiketsiz projelerde CSV export başarısız oluyordu.
  Düzeltildi: karanlık mod yorum kutusunda imleci gizliyordu.
  Daha hızlı: pano, 100'den fazla projesi olan çalışma
  alanlarında daha çabuk açılıyor.

Hata düzeltmesi notları nereden gelir?

Hatayı düzelten pull request’ten ve onu tetikleyen rapordan gelirler. Bildiren kişinin sözleri düzeltmeyle birlikte yol alırsa, belirtinin yarısı yazılmış demektir.

Özellik talebi mi hata mı yazısı, bir raporu doğru etiketlemenin sahibini neden belirlediğini anlatır. Changeloop’ta widget üzerinden bildirilen bir hata bug etiketli bir GitHub issue’su olur ve changelog girdisi merge edilen pull request’ten taslak olarak hazırlanır, yayımlanmadan önce bir insanın onaylaması için bekletilir. Release notes şablonu elle yazmak için aynı girdi şeklini verir: belirti, kapsam, aralık, eylem.

FAQ

Hata düzeltmesi release notes neleri içermeli? Her girdi kullanıcının gördüğü belirtiyi, kimin etkilendiğini, hangi sürümden ya da tarihten beri olduğunu, düzeltmenin tam olup olmadığını ve okuyucunun ne yapması gerektiğini, “hiçbir şey” dahil, adlandırmalı.

Her hata düzeltmesi release notes’ta listelenmeli mi? Hayır. Bir kullanıcının fark edebildiği, zaman kaybettiği ya da etrafından dolaştığı olanları listeleyin ve kozmetik ya da dahili düzeltmeleri kısa bir “Küçük düzeltmeler” listesine toplayın. Changelog, bir tanesine bakması gereken herkes için her düzeltmeyi tutar.

Kendi getirdiğiniz bir hata için release notes nasıl yazılır? Bunun bir regresyon olduğunu söyleyin, onu getiren release’i ve düzelten release’i adlandırın ve okuyuculara bir geçici çözümü kaldırıp kaldıramayacaklarını bildirin. Düz bir ifade, yumuşatılmış bir ifadeden daha iyi okunur.

Kullandığınız bir ürünün release notes’unu nasıl kontrol edersiniz? Ürünün yardım menüsünden, alt bilgisinden ya da dokümantasyonundan bağlanan bir changelog ya da release notes sayfasına bakın; açık kaynak projelerde ise deponun releases sekmesine.

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

changeloop'ta ilgili sayfalar: Release notu şablonu