GitHub release notes: üretin, sonra okunur hale getirin

GitHub release notes, deponun Releases sayfasındaki bir release’e iliştirilen açıklamadır ve GitHub bunların ilk taslağını önceki tag’den beri merge edilen pull request’lerden sizin için yazabilir. Taslak, etikete göre gruplanmış pull request başlıklarından, bir katkıda bulunanlar satırından ve bir compare bağlantısından oluşur. Doğrudur, eksiksizdir ve pull request’leri merge eden insanlar için yazılmıştır. Onu projenin bir kullanıcısının okuyabileceği bir şeye çevirmek bir .github/release.yml dosyası ve kısa bir düzenleme adımı ister; ikisi de aşağıda anlatılıyor.

GitHub’da release notes otomatik olarak nasıl üretilir?

Release formunu açın, tag’i seçin ya da oluşturun ve “Generate release notes” düğmesine tıklayın. GitHub önceki release tag’ini bulur, iki tag arasında hedef branch’e merge edilen her pull request’i listeler ve her pull request için başlığı, yazarı ve numarasıyla bir satır yazar. Komut satırından gh release create <tag> --generate-notes aynı şeyi yapar ve release’i tek adımda yayımlar; --notes-start-tag aralığın hangi eski tag’den başlayacağını değiştirir.

Özellik pull request’lerden beslenir, bu yüzden pull request olmadan doğrudan main’e merge eden bir depo boş bir taslak alır. Squash merge’ler sorun değildir, çünkü pull request hâlâ vardır. Uzun ömürlü bir branch’ten main’e yapılan merge commit’leri, merge eden pull request için tek satır üretir ve o branch’e daha önce merge edilen pull request’lerin hiçbiri görünmez. Aralık yanlış görünüyorsa olağan neden eksik ya da yanlış sıralanmış bir önceki tag’dir; üretici hedef branch’teki en son release’i kullanır ve release’i olmayan bir tag yok sayılır.

GitHub Docs’un otomatik üretilen release notes sayfası düğmeyi, gh release create kılavuzu ise CLI bayraklarını anlatır.

release.yml neyi değiştirir?

.github/release.yml, üreticiye hangi pull request’lerin dışarıda bırakılacağını ve kalanların nasıl gruplanacağını söyler. O olmadan her pull request, Dependabot dahil, tek bir listeye düşer. Onunla pull request’ler etikete göre kategorilere ayrılır ve etiketli ya da bot yazarlı gürültü kaybolur.

# .github/release.yml
changelog:
  exclude:
    labels:
      - skip-changelog
    authors:
      - dependabot
      - renovate
  categories:
    - title: Breaking changes
      labels:
        - breaking-change
    - title: New
      labels:
        - enhancement
    - title: Fixed
      labels:
        - bug
    - title: Other changes
      labels:
        - "*"

Bilinmesi gereken üç kural var. Kategoriler sırayla eşleştirilir, bu yüzden hem breaking-change hem bug etiketi olan bir pull request eşleşen ilk başlığın altına girer. Etiketsiz pull request’lerin görünmesini istiyorsanız "*" genel yakalayıcısı şarttır; o olmadan sessizce düşerler. Ve dosya yalnızca üreticinin yazdığını etkiler, bu yüzden onu değiştirmek zaten var olan notlara dokunmaz. Pull request’leri CI’daki changelog kontrolü için zaten etiketleyen ekipler aynı etiketleri burada yeniden kullanabilir.

Üretilen GitHub release notes neden kötü okunur?

Çünkü bir pull request başlığı gözden geçiren kişi için, değişiklik bitmeden önce yazılır ve kodu anlatır. “Export worker’ı streaming kullanacak şekilde refactor et” iyi bir pull request başlığı ve işe yaramaz bir release notu; çünkü release’i okuyan kişi 100 MB üzerindeki export’ların artık zaman aşımına uğramadığını öğrenmek istiyor.

İkinci neden, merge edilen her pull request’in eşit ağırlık almasıdır. Tek satırlık bir yazım hatası düzeltmesi, yeni bir kimlik doğrulama akışının yanında, hangi sırayla merge edildilerse o sırada durur. Okuyucu kendisini etkileyen üç satırı bulmak için bütün listeyi taramak zorundadır.

Üçüncüsü, taslağın bir açılışı yoktur. Üstünde tek cümle olmayan kırk satırlık bir liste, bu release’in alınmasının güvenli olup olmadığını, bir geçiş gerektirip gerektirmediğini ya da sadece bir bağımlılığı sabitlemek için var olup olmadığını kimseye söylemez.

Düzenleme adımı neyi değiştirmeli?

Üretilen listeyi tutun ve üzerine ekleyin, sıfırdan yeniden yazmayın. Liste denetim izidir; pull request numaraları, birinin bir satırı diff’e kadar takip etmesinin yoludur. Düzenleme adımı, üreticinin bilemeyeceği parçaları ekler.

1. En üste iki ya da üç cümle yazın. Bu release ne için, yükseltmek bir eylem gerektiriyor mu ve önce ne okunmalı. Breaking change varsa bunu ilk satırda söyleyin.
2. İnsanların önemseyeceği satırları okuyucunun tarafından yeniden yazın: kaybolan belirti, artık yapabildikleri şey, yer değiştiren ayar. Pull request numarasını satırın sonunda bırakın. Release notes nasıl yazılır tam şekli verir; hata düzeltmesi release notes özellikle düzeltme satırlarını ele alır.
3. Okuyucunun yapması gereken her şeyi kendi bölümüne taşıyın, tam komut ya da ayarla birlikte. “Other changes” listesine gömülmüş bir breaking change, bir hafta sonra bir destek bileti demektir.
4. Üretilen listeden hiçbir şey silmeyin. Uzunsa bir “Full list of changes” başlığı altında daraltın, ama tutun; çünkü projenin kendi katkıda bulunanları onu kullanır.

Bu şekilde yapıldığında GitHub release notes’u tipik bir release için düzenlemek yaklaşık on dakika sürer ve notlar iki kitleye de hizmet eder: üstteki özet kullanıcılar için, alttaki liste katkıda bulunanlar için.

GitHub release’i changelog’unuz olmalı mı?

Yalnızca bir değişiklikten haberdar olması gereken herkes zaten Releases sayfasını okuyorsa. Geliştiricilerin bir paket yöneticisi üzerinden tükettiği bir kütüphane için bu çoğu zaman doğrudur ve Releases sayfası artı depodaki bir CHANGELOG.md yeterlidir. Kullanıcıları hiç GitHub açmayan bir ürün için değildir: release sayfası yanlış seviyede yazılmıştır, geliştiriciye dönük bir URL’nin arkasında yaşar ve GitHub hesabı olmayan biri tarafından abone olunamaz.

Ayakta kalan desen, GitHub release’ini geliştiriciye dönük kayıt, ürün changelog’unu okuyucuya dönük kayıt olarak ele almak ve release’in changelog girdisine bağlantı vermesidir. Git tag’leri, release’ler ve changelog üç kaydın nasıl hizalandığını anlatır. Ürün changelog’u aynı commit’lerden üretiliyorsa, bir changelog generator o taraf için de bir taslak verir ve changelog vs release notes ayrımı hangi ayrıntının nereye ait olduğunu açıklar.

Release notes’un kendisi nasıl versiyonlanır?

GitHub’da yayımlanmış bir release her an düzenlenebilir ve düzenleme sayfada görünür bir geçmiş bırakmaz. Çoğu proje için bu sorun değildir. Notların uyumluluk ekiplerinin ya da müşterilerin güvendiği bir kayıt olduğu projelerde iki alışkanlık yardımcı olur: asıl metni depoda tutun (CHANGELOG.md ya da bir docs/releases/ klasörü) ve release gövdesinin ona işaret etmesini sağlayın; planınız sunuyorsa depoda immutable release’leri etkinleştirin, bu yayımlandıktan sonra tag’i ve varlıkları kilitler. GitHub Docs’un release yönetimi sayfası taslakları, ön sürümleri ve siz elle ayarlamadıkça semantic version sırasına göre atanan “latest” etiketini anlatır.

FAQ

GitHub release notes otomatik olarak üretilebilir mi? Evet. Release formundaki “Generate release notes” düğmesi, gh release create üzerindeki --generate-notes bayrağı ve generate-notes REST endpoint’i, hepsi önceki release tag’inden beri merge edilen pull request’lerden bir taslak üretir. Bir .github/release.yml dosyası gruplamayı ve dışlamaları denetler.

Üretilen release notes’um neden boş? Üretici pull request’leri listeler, bu yüzden branch’e doğrudan yapılan commit’ler görünmez ve aralık en son tag’den değil hedef branch’teki en son release’ten başlar. Önceki release’in var olduğunu ve değişikliklerin pull request üzerinden geldiğini kontrol edin.

release.yml zaten var olan release’lere uygulanır mı? Hayır. Yalnızca dosya yerine konduktan sonra üretilen notları şekillendirir. Mevcut release gövdeleri biri düzenleyene kadar olduğu gibi kalır.

GitHub release notes mu yoksa CHANGELOG.md mi kullanmalıyım? Projenin hem katkıda bulunanları hem kullanıcıları varsa ikisini de. Release sayfası geliştiricilerin baktığı ve varlıkların yaşadığı yerdir; depodaki dosya GitHub’dan ayrılmaya dayanır ve çevrimdışı okunabilir. Release notes’u üretin, dosyayı güncel tutun ve birini diğerine bağlayın.

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

changeloop'ta ilgili sayfalar: Changelog oluşturucu, Geliştirici dokümantasyonu