Commit'ler ve ekran görüntülerinden otomatik sürüm notları

Neden sürüm notları ekstra iş gibi gelir

Sürüm notları faydalı olduğu konusunda herkesin hemfikir olduğu ama sıklıkla haftanın sonuna ertelenen işlerdendir. Yoğun birkaç sprintin ardından bir koşuşturma paragrafına dönüşür veya tamamen atlanır.

Sorunun bir kısmı zamanlamada. Detaylar commitlerde, PR sohbetlerinde ve hızlı mesajlarda duruyor. Değişikliği yazmak için oturduğunuzda neden önemli olduğunu, kimin etkilendiğini ve kullanıcının gerçekte ne fark edeceğini hatırlamaya çalışırsınız.

Bir de dil uyumsuzluğu var. Geliştiriciler "refactor auth middleware" veya "fix race in cache" gibi yazar; kullanıcılar ise "Oturum açma daha güvenilir" veya "Yavaş bağlantılarda sayfalar daha hızlı yükleniyor" duymak ister. Teknik işi kullanıcı diline çevirmek odak gerektirir ve bağlam değiştirirken yapmak zordur.

Biçim farkı durumu daha da kötüleştirir. Bir hafta madde işaretleri kullanırsınız, diğer hafta paragraflar. Biri emoji ekler, diğeri ticket kimliğini yazar. Zamanla changelog hızlı taranamaz hale gelir ve güvenilirliği düşer.

İyi haber: çoğu ham materyali zaten üretiyorsunuz. Küçük bir PR açıklaması ve birkaç UI ekran görüntüsü genelde gereken her şeyi içerir. Amaç roman yazmak değil; aynı formatta, kullanıcı dostu notlar üretmek.

Basit bir yaklaşım en iyi sonucu verir:

• "Ne değişti"yi PR'da yakalayın, sadece "nasıl"yı değil.
• Değişikliği kanıtlayan 1–2 ekran görüntüsü kaydedin.
• Her seferinde aynı şablona dönüştürün.

Commitler, PR notları ve UI ekran görüntülerinden ne kastettik

Tutarlı sürüm notları almak için elinizdeki girdiler konusunda net olun. Çoğu ekip yeterli detaya sahip; sadece dağınık durumda.

Bir commit, en küçük birimdir: koddaki değişikliğin teknik kaydı. Commit mesajları işi izlemek için faydalıdır, ama genelde müşterinin okumak isteyeceği şekilde olmaz.

Bir PR (pull request) açıklaması köprüdür. Değişikliğin neden var olduğunu, bir inceleyenin ne kontrol etmesi gerektiğini ve ürün açısından ne değiştiğini açıklar. Otomatik sürüm notu istiyorsanız, PR açıklamaları genelde en iyi ham materyaldir çünkü uzun olmadan sade dille yazılabilirler.

Issue başlıkları (veya ticket başlıkları) çözülen soruna başka bir ipucu verir: PR'lar issue'lara referans veriyorsa "raporlanan sorun"dan "yayınlanan düzeltme"ye temiz bir iz hattı elde edersiniz.

Bir UI snapshot (ekran görüntüsü veya kısa notlu resim) kullanıcının gerçekten ne göreceğinin görsel kaydıdır. Dekorasyon değildir; kanıt ve bağlamdır.

Sürüm notu çıktıları genelde iki türe ayrılır:

• Dahili changelog (tam, teknik, uç durumları içerir)
• Kullanıcıya yönelik sürüm notları (kısa, net, fayda ve davranış değişikliklerine odaklı)

Farklı kitleler bu notları farklı amaçlarla okur. Müşteriler bugün kendileri için ne değiştiğini bilmek ister. Destek ekibi ne bekleyeceğini ve kullanıcılara ne söyleyeceğini bilmek ister. Satış ve başarı ekipleri neyin yeni ve söylenecek olduğunu arar. İç ekipler ise ne yayınlandığını ve neyin bozulabileceğini kaydetmek ister.

Ekran görüntüleri üç konuda işe yaradığı zaman en faydalıdır: değişikliğin gerçek olduğunu doğrulamak, kesin etiket ve buton adlarını hatırlatmak ve metnin anlatamadığını görsel olarak göstermek.

Bir kez basit bir changelog yapısı seçin

İyi bir changelog yazmaktan çok sınıflandırmakla ilgilidir. Yapı her sürümde aynı kalırsa, küçük PR notlarını her seferinde formatı yeniden düşünmeden sürüm notlarına dönüştürebilirsiniz.

İnsanların tanıyacağı kategoriler seçin

Kullanıcıların ürününüz hakkında konuşma biçimine uyan 4–6 kategori seçin. Çok fazla kutu işleri yavaşlatır ve "çeşitli" yığınları yaratır.

Pratik bir set:

• Yeni
• İyileştirmeler
• Düzeltmeler
• Güvenlik
• Yönetici

"Yönetici" faturalar, roller veya ayarlarla ilgili değişiklikler için kullanışlıdır. Ürününüz geliştirici odaklıysa bunu "API" ile değiştirebilirsiniz. İsimleri sabit tutun ki okuyucular nerede arayacaklarını öğrenebilsinler.

Kullanıcıya dönük ile dahili arasında net bir çizgi çizin. Basit bir kural: bir kullanıcı bunu fark edebiliyorsa, arayabiliyorsa veya buna güvenebiliyorsa, sürüm notlarına girer. Sadece refactor, bağımlılık güncellemesi veya log değişikliği ise davranış değiştirmedikçe dışarıda bırakın.

Cümle kalıbını standartlaştırın

Bir cümle kalıbı seçin ve ona bağlı kalın. Bu, PR açıklamalarının mini denemelere dönüşmesini engeller ve nihai notları taramayı kolaylaştırır.

Güvenilir bir kalıp:

Ne değişti + kim etkilendi + nerede bulunur.

Örnek: "Ayarlar'da çalışma alanı sahipleri için iki faktörlü giriş eklendi." Tonu sonra değiştirmek isteseniz bile ham girdi tutarlı kalır.

Küçük bir sözlük beklenenden daha çok işe yarar. Her ana kavram için bir terim seçin ve eşanlamlı kullanmayın (örneğin hep "çalışma alanı" deyin, bazen "proje" veya "takım alanı" demeyin). Tutarlı ifadeler sürüm notlarının tek bir ses gibi görünmesini sağlar.

Sürüm notlarına dönüşecek şekilde PR açıklamaları yazın

Otomatik sürüm notu almanın en kolay yolu her PR'ı küçük, kullanıcıya yönelik bir hikaye gibi ele almaktır. Takım dışından biri PR başlığını okuyup ne değiştiğini anlayabiliyorsa, işin büyük kısmı tamamdır.

PR başlığıyla başlayın. Uygulamaya değil sonuca odaklı, tek cümle, sade bir başlık yapın. "Add caching layer to search" yerine "Search results load faster" gibi bir başlık, doğrudan changelog'a kopyalanabilir.

PR açıklamasını kısa tutun (2–5 satır), ama her satırın bir işi olsun:

• Niyet: hangi sorunu çözdünüz
• Kullanıcı etkisi: kim fayda sağlıyor ve nasıl
• Uç durumlar: limitlerde, izinlerde veya varsayılanlarda ne değişiyor
• Risk veya yayılma notu: yayından sonra nelere dikkat edilmeli
• Destek notu: kullanıcı sorarsa ne denmeli

Etiketler daha sonra sıralarken yardımcı olur. [UI], [API], [Billing], [Performance] gibi tutarlı köşeli parantezler kullanın. Bir veya iki etiket yeterlidir; çok fazla etiket gürültüye dönüşür.

Her PR açıklamasına bir "Kullanıcı etkisi" satırı ekleyin; bu satır sürüm notu olarak okunacak şekilde olsun. Örnek: "Yöneticiler faturaları CSV olarak indirebilir." Bu satır, zaman kıt olduğunda altın değerindedir.

UI değiştiğinde ekran görüntülerini PR açıklamasına ekleyin. Değişen alanı daraltarak kırpın. Görünür bir değişiklik yoksa ekran görüntüsü atlayın ve farkı açıklayan bir satır daha yazın.

Yapıştırılabilecek basit PR açıklama şablonu:

[UI] Faster search results

Intent: Reduce wait time on the search page.
User impact: Everyone sees results in under 1 second for common queries.
Edge cases: Empty search now shows “Try a different keyword”.

Ekran görüntülerini yararlı, değil gürültülü yapın

Ekran görüntüleri sürüm notu yazarken saatler kazandırabilir, ama yalnızca kolay bulunup anlaşılırsa. "Screenshot 12" gibi rastgele isimlendirilmiş bir resim işleri daha da çoğaltır.

Basit bir adlandırma düzeniyle başlayın, böylece sonra arama yapabilirsiniz. Bir seçenek YYYY-MM-DD_area_feature_state olabilir. Örnek: 2026-01-14_billing_invoices_empty.png. "Bu ekran ne zaman değişti?" sorusuna saniyeler içinde cevap verebilirsiniz.

Hikâyeyi anlatan durumu yakalayın. "Mutlu yol" her zaman en faydalı olmayabilir. Bir sürüm davranış değiştiriyorsa, kullanıcının fark edeceği anı gösterin.

Neler yakalanmalı (çoğu ekip bunları kaçırır)

Her değişiklik için 1–3 ekran görüntüsü hedefleyin. En faydalı olanlar genelde:

• Boş durum (ilk kullanıcı görünümü, henüz veri yok)
• Hata durumu (doğrulama mesajı, başarısız ödeme, izin reddi)
• Başarı durumu (kaydedildi, gönderildi, tamamlandı)
• Görünür erişilebilirlik değişiklikleri (etiketler, odak çizgisi, kontrast)

Notları hafif tutun. Görselin açıklamaya ihtiyacı varsa bir ok veya vurgulama yeterli. Görselin üzerine paragraf koymayın; açıklamayı PR açıklamasında yapın, böylece changelog'da tekrar kullanılabilir.

Ekran görüntülerini nereye koyduğunuz da en az ne yakaladığınız kadar önemlidir. Ekran görüntülerini PR yanında (veya paylaşılan bir klasörde) kaydedin ve dosya adına veya başlığa PR ID'si ekleyin. Örnek: "PR-1842: updated checkout error message." Böylece birisi sorduğunda değişikliği hızla izleyebilirsiniz.

Küçük ama kazandıran bir alışkanlık: UI metni, boşluk veya kontrast değiştirdiğinizde bir satırlık not ekleyin: "Okunabilirlik için buton kontrastı iyileştirildi." Bu satır çoğu zaman ekstra düzenleme olmadan temiz bir sürüm notuna dönüşür.

Adım adım iş akışı: PR'lardan sürüm notlarına

Güvenilir sürüm notları almak için süslü bir sisteme ihtiyacınız yok. Bir küçük alışkanlığa ihtiyacınız var: her merge edilen PR kısa, kullanıcıya dönük bir not içermeli ve her UI değişikliğinin buna uygun bir ekran görüntüsü olmalı.

Basit bir haftalık akış

Bir yayın penceresi seçin (örnek: Pazartesi–Cuma). Bu pencere içinde merge edilen PR başlıklarını ve açıklamalarını tek bir taslak belgeye çekin. Bir PR'nın net açıklaması yoksa tahmin etmeyin; bağlam taze iken yazardan bir satır eklemesini isteyin.

Ekran görüntülerini UI'yi değiştiren PR'larla eşleştirin. Görünür değişiklik başına genelde bir ekran görüntüsü yeterlidir. Dosyaları etiketleyin ki neyi gösterdiği belli olsun (fark ince ise önce/sonra yardımcı olur).

Sonra hızlı bir temizlik turu yapın:

• Maddeleri sabit kategorilerinize göre gruplayın (örnek: Yeni, İyileştirmeler, Düzeltmeler)
• Yinelenenleri birleştirin (iki PR aynı özelliği getirdiyse tek bir not yapın)
• Dahili detayları çıkarın (ticketlar, refactorlar, kütüphane güncellemeleri)
• Her maddeyi kullanıcı dilinde, sonuca odaklı olarak yeniden yazın
• Şablonunuzu uygulayın ki her not tek bir fiil içeren cümle olsun

Hızlı bir gözden geçirme ile bitirin. Taslağı destek veya ürünle paylaşın ve tek bir soru sorun: "Bir müşteri ne değiştiğini ve neden önemli olduğunu anlayabilir mi?" Eğer cevap hayırsa, dili sadeleştirin veya ufak bir bağlam ekleyin.

Örneğin "Refactored permissions middleware" yerine "Artık Rol Yönetimi sayfasından ekip rollerini yönetebilirsiniz" yazın.

Ham değişiklik detaylarını kullanıcı dostu metne dönüştürme

Ham girdiler (commit mesajları, PR notları ve ekran görüntüleri) takım arkadaşları için yazılır. Sürüm notları kullanıcılar için yazılır. İş kopyala-yapıştır değil, çeviridir.

Bazı yazım kuralları her girdiyi net tutar:

• Etken cümle kullanın: "Fatura filtreleri eklendi" yerine "Fatura filtreleri eklendi" daha doğrudur.
• Kısaltmalardan ve dahili isimlerden kaçının. Kullanmak zorundaysanız bir kere açın.
• Kullanıcının tanıyacağı ekran adını yazın: "Faturalama ayarları", "PaymentsModule" değil.
• Önce faydayı sonra değişikliği söyleyin: "Faturaları bulmayı hızlandırmak için yeni filtreler eklendi."
• Her maddeyi tek bir fikirle sınırlayın.

Tutarlılık mükemmel sözcükten daha önemlidir. Bir zaman çekimini seçin (çoğu ekip geçmiş zaman kullanır: "Düzeltildi", "İyileştirildi", "Eklendi") ve ona bağlı kalın. İsimlendirmede tutarlılık sürüm notunun dağınıklığını önler.

Kırıcı değişiklikler: ne yapılacağına odaklanın

Bir şey kullanıcıyı etkileyecekse, açıkça söyleyin ve bir sonraki adımı verin. Teknik sebebi atlayın.

Örnek: "10 Ocak'tan önce oluşturulan API anahtarları çalışmayı durduracak. Ayarlar - API anahtarları'ndan yeni bir anahtar oluşturun."

Bilinen sorunlar: kısa, dürüst, yardımcı

Kullanıcıların muhtemelen karşılaşacağı durumlarda "Bilinen sorunlar" bölümü ekleyin; kısa tutun ve bir çözüm varsa yazın.

Örnek: "Bilinen sorun: Çok büyük raporlarda CSV dışa aktarımı zaman aşımına uğrayabilir. Çözüm: tarih aralığına göre dışa aktarın."

Ekran görüntüleri yerlerini hak etmelidir. Yeni bir kontrolü, taşınmış bir butonu veya yeni bir ekranı kullanıcıların bulmasını kolaylaştırıyorsa bir tane ekleyin. Küçük düzenlemeler (boşluk, renk, küçük metin değişiklikleri) içsel ise veya bir sonraki sürüme kadar değişebilecekse ekran görüntülerini dahili tutun.

Zaman kaybettiren yaygın hatalar

Çoğu sürüm notu sıkıntısı özelliğin yayınlanmasından bir hafta sonra ortaya çıkar. Biri "Bu değişiklik kasıtlı mı?" diye sorar ve siz PR'larda, ekran görüntülerinde ve sohbetlerde kazı yaparsınız. Otomatik sürüm notlarını faydalı tutmak istiyorsanız, notları okunamaz ve güvenilmez hale getiren tuzaklardan kaçının.

Temizleme işi yaratan hatalar

En çok aşağıdaki kalıplar tekrar düzenleme gerektirir:

• Kullanıcıya yönelik notlarda commit hashleri veya dahili ticket ID'leri bırakmak. Takım için yardımcı olabilir ama müşteriye gürültü gibi görünür.
• PR açıklamasını olduğu gibi kopyalamak. PR metni genelde inceleyici için yazılır, işi yapan kişi için değil.
• Geleceğe dair sözleri ("yakında") yayınlanmış değişikliklerle karıştırmak. "Yakında" yol haritasına aittir, sürüm notlarına değil.
• Alakasız değişiklikleri tek bir maddeye doldurmak. Bir madde içinde beş güncelleme olursa destek doğru cevabı veremez.
• Erişim ve izin etkilerini unutmak. Roller değiştiyse, kimlerin ne yapabileceğini açıkça yazın, UI aynı görünse bile.

Küçük UI değişiklikleri sıkça atlanır. Yeniden adlandırılmış bir buton, taşınmış bir menü öğesi veya yeni bir boş durum, bir backend refactorundan daha çok kullanıcıyı şaşırtabilir. Ekran görüntüsü değiştiyse, kısaca bahsedin: "Dışa Aktar butonu tablonun sağ üstüne taşındı" çok fazla geri dönüşü önler.

Örnek: Yeni bir faturalama düzeni yayınladınız ve fatura düzenleme yetkisini de sıkılaştırdınız. Sadece "Faturalama sayfası iyileştirildi" yazarsanız yöneticiler başka bir şey değişmediğini varsayar. Daha iyi bir yaklaşım: düzen değişikliği için bir satır, rol değişikliği için ayrı bir satır yazın ve rolü adlandırın.

İyi sürüm notları daha uzun değildir; daha nettir ve zamanla eskimez.

Yayınlamadan önce hızlı kontrol listesi

İyi bir sürüm notu üç soruyu hızlıca yanıtlar: ne değişti, nerede görmek gerekir ve kim için önemli. Yayına basmadan önce taze gözle bir tur daha atın.

Son kontrol listesi

Her maddeyi kullanıcı değil de yapımcı gibi değil, kullanıcı gibi okuyun. Anlamını tahmin etmeniz gerekiyorsa yeniden yazın.

• Her giriş ne değiştiğini ve nerede bulunacağını söylüyor (sayfa/ekran adı, menü yolu veya buton etiketi).
• Her giriş kimin etkilendiğini belirtiyor (tüm kullanıcılar, sadece yöneticiler, sadece mobil, belirli plan, belirli rol).
• Kırıcı değişiklikler net şekilde etiketlenmiş ve bir sonraki adımı içeriyor (ayar güncelle, yeniden kimlik doğrulama, veri taşıma, destekle iletişim).
• Ekran görüntüleri yalnızca kafa karışıklığını gideriyorsa dahil edildi ve gerekli alanlara kırpıldı.
• Biçimlendirme alıştığınız yapıya uyuyor: aynı kategoriler, benzer madde uzunluğu ve her madde tek bir fikir içeriyor.

Kontrolden sonra küçük bir "çeviri" turu daha yapın. Dahili kelimeleri (ticket ID'leri, bileşen adları, feature flag'ler) kullanıcıların tanıyacağı terimlerle değiştirin. Bir özellik rollout aralığındaysa veya yalnızca belirli bir planda ise bunu doğrudan yazın.

Bir akıl testi

Mühendislik dışından bir kişiye okutun. Kurucu, destek, satış veya bir arkadaş olabilir. Eğer onlar 10 saniyede "Ne değişti?" sorusuna cevap veremiyorsa metin hâlâ PR'a çok yakın.

Örnek: "Settings modal durum yönetimi iyileştirildi" yerine "Ayarlar sekmeleri arasında geçiş yaptıktan sonra değişiklikler artık doğru şekilde kaydediliyor" yazın.

Gerçekçi bir örnek: ekran görüntüleriyle haftalık sürüm notları

Küçük bir ekip haftada 12 PR yayınlıyor: 4 UI düzenlemesi, 2 hata düzeltmesi ve geri kalanı küçük refactor ve testler. Otomatik sürüm notu istiyorlar ama yine de insan tarafından yazılmış gibi okumasını istiyorlar.

Cuma'ya kadar beklemek yerine, girdileri çalışırken toplarlar. Her PR bir "kullanıcıya dönük not" satırı içerir ve UI değiştiyse bir önce/sonra ekran görüntüsü eklenir. Ekran görüntüleri PR notlarının yanına kaydedilir, böylece daha sonra sohbetlerde arama yapmak gerekmez.

Cuma geldiğinde, biri PR notlarını tarar ve benzer değişiklikleri gruplar. Dört küçük UI düzenlemesi bir kullanıcı maddesine dönüşür, üç iç refactor kullanıcı açısından önemsiz olduğu için çıkarılır.

Yayınlanan haftalık changelog şu şekilde görünür:

• Faturalama sayfası düzeni ve etiketleri iyileştirildi; toplamlar ve vergi detayları daha net (ekran görüntülerine bakın).
• Filtreleme yapıldığında CSV dışa aktarımında son satırın eksik olmasına neden olan bir sorun düzeltildi.
• Bir çalışma alanını silmeden önce onay adımı eklendi, kazaları önler.
• Çok sayıda proje olan hesaplarda pano yükleme süresi iyileştirildi.

Yeniden yazma işleri çoğu ekibin zamanını geri kazandırdığı yerdir. "Refactor billing-summary component, rename prop, update tests" gibi bir PR notu "Faturalama sayfası düzeni ve etiketleri iyileştirildi" haline gelir. "Fix N+1 query in projects list" ise "Çok sayıda proje olduğunda pano yükleme süresi iyileştirildi" olur.

Ekran görüntüleri, metin değiştiğinde kafa karışıklığını engeller. Bir butonun etiketi "Archive"den "Deactivate"e değiştiyse, görsel kullanıcının ne göreceğini açıkça gösterir ve destek hangi ekrana bakacağını tahmin etmek zorunda kalmaz.

Sonraki adımlar: alışkanlık haline getirin ve sıkıcı işleri otomatikleştirin

"Bir kere denedik" ile sürekli yapılan arasındaki en büyük fark küçük bir rutindir. Her yayın penceresi için bir kişi notlardan sorumlu olsun ve ona sabit 30 dakikalık bir zaman ayırın. Sahibi ve zaman kutusu olduğunda iş herkesin sorunu olmaktan çıkar.

PR şablonunu ve ekran görüntüsü kurallarını normal işin parçası yapın, özel bir süreç değil. Bir PR kullanıcıya yönelik kısa satır veya önce/sonra görüntüsü eksikse, bu "ekstra cilâ" değil; eksik bilgi demektir.

Hafif bir taslak dokümanı alışkanlık haline getirmek işe yarar. Mevcut yayın için tek bir sürekli taslak tutun ve PR'lar merge oldukça güncelleyin. Yayın günü düzenleme olur, sıfırdan yazmak olmaz.

İyi çalışan küçük bir ritim:

• Haftalık (veya sprintlik) dönüşümlü bir sürüm-notları sahibi atayın.
• Her PR açıklamasında kısa bir "kullanıcı etkisi" satırı zorunlu kılın.
• Sadece anlamlı UI anlık görüntülerini kaydedin (yeni ekran, değişen akış, düzelen hata).
• Her merge edilen PR'ı seçtiğiniz başlıklar altına ekleyin.
• Son 30 dakikada dili sıkılaştırın ve yinelenenleri çıkarın.

Biçimlendirme hâlâ çok zaman alıyorsa, küçük bir iç taslak oluşturucu yapın. PR metnini okuyup şablon başlıklarını uygulayan ve temiz bir taslak üreten hafif bir araç işi büyük ölçüde azaltır. Küçük adımla başlayın: başlıklarla gruplayıp ekran görüntüsü başlıklarını çekmek çoğu zaman yeterlidir.

Eğer bu tür bir oluşturucu prototiplemek isterseniz, Koder.ai (koder.ai) bir seçenek olabilir. Prompt ve çıktı formatı üzerinde hızlıca iterasyon yapıp hazır olduğunuzda kaynak kodu dışa aktarabilirsiniz.