03 Oca 2026·6 dk
Commit'ler ve ekran görüntülerinden otomatik sürüm notları
Commit'ler ve ekran görüntülerinden otomatik sürüm notları: küçük PR notlarını ve UI görüntülerini tutarlı, kullanıcı dostu changelog'lara dönüştürmenin basit iş akışı.
Commit'ler ve ekran görüntülerinden otomatik sürüm notları: küçük PR notlarını ve UI görüntülerini tutarlı, kullanıcı dostu changelog'lara dönüştürmenin basit iş akışı.
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:
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:
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.
İ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.
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:
"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.
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.
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:
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ü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.
Her değişiklik için 1–3 ekran görüntüsü hedefleyin. En faydalı olanlar genelde:
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.
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ı.
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:
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 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:
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.
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."
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.
Ç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.
En çok aşağıdaki kalıplar tekrar düzenleme gerektirir:
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.
İ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.
Her maddeyi kullanıcı değil de yapımcı gibi değil, kullanıcı gibi okuyun. Anlamını tahmin etmeniz gerekiyorsa yeniden yazın.
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.
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.
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:
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.
"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:
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.
PR başlıkları ve açıklamalarını birincil kaynak olarak kullanın; çünkü genellikle “neden” ve kullanıcıya etkisini içerir. Commitler kod değişikliklerini izlemek için iyidir ama genelde müşteri dilinde yazılmaz.
Başlığı kullanıcının fark edeceği sonuç üzerine, sade bir dilde yazın. Eğer küçük düzenlemelerle changelog’a kopyalanabiliyorsa, doğru yoldasınız demektir.
Kısa ve tutarlı tutun: ne değişti, kim etkilendi ve nerede bulunur. Bu, belirsiz notları önler ve girdileri taramayı kolaylaştırır.
Kullanıcıların tanıyacağı 4–6 kalıcı kategori seçin: örneğin Yeni, İyileştirmeler, Düzeltmeler, Güvenlik ve Yönetici. Aynı kovaları her seferinde kullanmak format sürüklenmesini azaltır.
Kullanıcı fark edebilecek, arayabileceği veya güvenebileceği bir şeyse dahil edin. Saf refactorlar, bağımlılık güncellemeleri ve log değişiklikleri davranışı değiştirmiyorsa kullanıcıya dönük notlara girmemeli.
UI değiştiğinde ve görüntü kafa karışıklığını azaltıyorsa ekran görüntüsü ekleyin: taşınmış bir buton, değiştirilmiş bir etiket veya akışta yeni bir adım gibi. Genelde bir net görsel (veya önce/sonra çifti) yeterlidir.
Tarihi ve ürün alanını içeren tutarlı, aranabilir bir adlandırma kullanın. Dosya adına veya başlığa PR kimliği ekleyin ki değişikliği hızlıca izleyebilesiniz.
Etkisini önce söyleyin ve kullanıcıların sonraki adımını verin. Teknik nedeni atlayın ve değişikliğin nereden yapılacağını açıkça belirtin.
Kullanıcıların muhtemelen karşılaşacağı bilinen sorunları yalnızca gerektiğinde ekleyin; kısa, dürüst ve yardımcı olun. Bir çözüm yolu varsa açıkça yazın.
Her birleştirilmiş PR’ı küçük bir kullanıcı hikayesi gibi ele alın; sonra belirlenen zaman aralığındaki PR notlarını derleyip sabit kategorilere göre gruplayın. Araçlar taslak oluşturmayı kolaylaştırır ama yine de kısa bir insan kontrolü gerekir.