changeloop blog

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

Fri, 02 Oct 2026 00:00:00 GMT

İ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.

Önce (commit mesajı)	Sonra (belirti)
Export handler'daki null pointer düzeltildi	Projenin etiketi olmadığında export'lar artık "Bir şeyler ters gitti" ile başarısız olmuyor. 3 Eylül'den beri başarısız olan export'ları yeniden çalıştırın.
Sync worker'daki race condition çözüldü	İki cihazda birkaç saniye arayla yapılan düzenlemeler artık birbirinin üzerine yazmıyor. Yapılacak bir şey yok.
Saat dilimi hatası düzeltildi	Zamanlanmış raporlar artık ayarladığınız saatte çalışıyor. UTC'nin doğusundaki hesaplar 12 Ağustos'tan beri raporları bir güne kadar erken gördü. Değişiklik gerekmiyor.
Yorum renderer'ındaki XSS yamalandı	Güvenlik düzeltmesi: özel hazırlanmış bir yorum başka bir kullanıcının tarayıcısında script çalıştırabiliyordu. Bugün 4.2.1'e yükseltin. Loglarımızda istismar görmedik.
4.1.0'dan gelen regresyon düzeltildi	Tire içeren sorgularda arama yeniden çalışıyor. 4.1.0'da bozuldu ve 4.1.1'de düzeldi.
Hata düzeltmeleri ve performans iyileştirmeleri	Hangilerini söyleyin. Son bölüme bakın.

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:

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.
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.
Aralık. Hangi sürümden ya da tarihten beri, böylece okuyucu dünkü tuhaf sonucun hata olup olmadığına karar verebilir.
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.

Kendi girdisini alır	Küçük düzeltmeler listesine girer
Bir müşteri bildirdi ya da çoğu kişi yaşadı	Nadiren açılan bir ekrandaki kozmetik aksaklık
Yanlış çıktıya, başarısız işlere veya kaybolan işe yol açtı	Yazım hatası, boşluk, hizası kayık bir simge
Okuyucudan bir eylem gerektiriyor	Dahili bir araçtaki ya da yönetici sayfasındaki düzeltme
Yakın bir release'ten gelen regresyon	Sadece test ortamında görülen hata
Faturalamaya, izinlere veya veriye dokunuyor	Log ifadesi, kullanıcı etkisi olmayan bağımlılık güncellemeleri

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.

Yazılım ürününde müşteriden geri bildirim nasıl istenir

Fri, 02 Oct 2026 00:00:00 GMT

Bir yazılım ürününde müşteriden geri bildirim istemek için, kullanıcının az önce yaptığı somut bir şey hakkında, onu yaptığı yerde tek bir soru sorun. Bir export'tan hemen sonra gelen "O rapor export'u nasıl geçti?" cevap alır. Alt bilgideki "Ürünümüz hakkında ne düşündüğünüzü bize söyleyin" sessizlik alır. Sayfanın geri kalanı anlar, kanallar ve tam cümlelerdir.

Bu konudaki öğütlerin çoğu mağazalar ve hizmet masaları için yazılmıştır. Bir yazılım ekibi kullanıcının bir saniye önce ne yaptığını tam olarak bilir, o yüzden soru ona dair olabilir.

An	Nerede sorulur	Hazır soru
Bir görev bittikten hemen sonra	Uygulamada, sonucun yanında	"Bu export ihtiyacınızı karşıladı mı?"
Yeni bir özelliğin ilk kullanımından sonra	Uygulamada, bir kez	"Toplu Düzenle ile ne yapmaya çalışıyordunuz?"
Bir destek ticket'ı çözüldükten sonra	Destek yazışmasında	"Bu çözdü mü, yoksa hâlâ ters giden bir şey var mı?"
Kullanıcı bir akışta durduktan veya terk ettikten sonra	E-posta, bir gün sonra	"Kurulumun 3. adımında durdunuz. Sizi ne engelledi?"
30 günlük düzenli kullanımdan sonra	Adı olan bir kişiden e-posta	"Değiştireceğiniz tek şey ne olurdu?"
Kullanıcı iptal ettiğinde	İptal akışında	"Bugün ayrılmaya sizi ne karar verdirdi?"
İstedikleri bir şeyi yayımladıktan sonra	İstedikleri yerde	"CSV içe aktarma istemiştiniz. Yayında. Sizin durumunuzu karşılıyor mu?"

Geri bildirim istemenin doğru zamanı ne zaman?

Doğru zaman, kullanıcı bir şeyi bitirdikten hemen sonradır, ayrıntı hâlâ aklındayken. Bir eylemi izleyen soru o eylem hakkında cevap alır. Durup dururken gelen soru, kişinin o anki ruh hali hakkında bir cevap alır, ya da hiç alamaz.

Kayıt sırasında sormayın, çünkü kimse henüz bir şey kullanmadı. Bir görevin ortasında sormayın, çünkü öğrenmek istediğiniz şeyi kesintiye uğratıyorsunuz. Biri cevap verdikten sonra, bildirecek bir şeyiniz olana kadar onu rahat bırakın.

Müşteriden geri bildirim nereden istenmeli?

Deneyimin yaşandığı yerden isteyin. Uygulama içi bir istem bir ekran hakkındaki soruya uyar. Destek yazışması bir düzeltme hakkındaki soruya uyar. E-posta bir haftalık kullanım ya da terk edilen bir akış hakkındaki soruya uyar. Bir görüşme, önceden tahmin edemeyeceğiniz sorulara uyar.

Her kanal farklı türde cevap getirir:

Uygulama içi: kısa, anında ve somut, ama sadece orada olan insanlardan. Ayrılan kullanıcılardan hiçbir şey duymazsınız.
Destek yazışması: yazmaya yetecek kadar bunalmış insanlardan. Bozuk şeyleri bulmak için iyi, ürünün geri kalanını yargılamak için zayıf.
E-posta: daha az insandan daha uzun cevaplar ve sessizleşen kullanıcılara ulaşmanın tek yolu. Adı olan bir kişiden, içinde tek bir soru bulunan kısa bir not olarak yazın.
Görüşme: insanların bir şeyi neden yaptığını öğrenmenin yolu. Onlardan nasıl çalıştıklarını göstermelerini isteyin ve onlar yaparken sessiz kalın.

Geri bildirim sinyal kalitesi her kanalın size söylediğini nasıl tartacağınızı anlatır.

Profesyonelce geri bildirim nasıl istenir?

Konuda somut olun, neden sorduğunuzu söyleyin ve cevabın bir dakikadan az sürmesini sağlayın. Profesyonel bir istem anı adlandırır, cevabı bir insanın okuyacağını belli eder ve kesinti için özür dilemez.

Tam eylemi adlandırın ("az önce çalıştırdığınız export"), tek bir şey isteyin, zorunlu alan olmayan serbest metin kutusu kullanın ve bir ilk adla imzalayın.

Geri bildirim istemek için iyi bir cümle nasıl olur?

İyi bir cümle, belirli bir an hakkında, birkaç kelimeyle cevaplanabilen bir sorudur. Aşağıdaki iki sütunu karşılaştırın. Soldakiler omuz silkerek cevaplanabilir. Sağdakiler kişinin gerçek bir şeyi hatırlamasını ister.

Zayıf istem	Daha güçlü istem
"Geri bildiriminiz var mı?"	"Bunu kurarken en zor kısım neydi?"
"Ürünümüzü nasıl buluyorsunuz?"	"Geçen hafta bunu ne için kullandınız?"
"Deneyiminizi 1'den 10'a puanlayın."	"Bugün yapmaya geldiğiniz işi bitirebildiniz mi?"
"Nasıl gelişebileceğimizi söyleyin."	"Bu hafta sizi yavaşlatan tek şey neydi?"
"Bizi tavsiye eder miydiniz?"	"Bunu en son kime gösterdiniz ve ne dediniz?"

Hemen her yerde işe yarayan bir başkası: "Bu sizin için işe yaramadığında yerine neyi kullanıyorsunuz?" Gerçek rakibi ortaya çıkarır, ki bu çoğu zaman bir e-tablodur.

Geri bildirim istemenin en kötü yolları nelerdir?

En kötü istemler geniş, erken, uzun ya da yönlendiricidir. Hepsinin ortak bir sorunu var: kişi, sizin yapmanız gereken düşünmeyi yapmadan cevap veremez.

"Lütfen 20 soruluk anketimizi doldurun." Bitirenler en çok boş zamanı olanlar ya da en güçlü fikri olanlardır.
Girişten sonraki ilk sayfada bir pop-up. Kullanıcı bir şey yapmaya geldi ve siz engellediniz. Kapatmak tek makul cevaptır.
Soru olmadan "Geri bildiriminizi çok isteriz!" Kullanıcıdan konuyu icat etmesini ister.
Yönlendirici bir soru: "Yeni panoyu ne kadar çok seviyorsunuz?" Onay alırsınız ve hiçbir şey öğrenmezsiniz.
Takibi olmayan bir puan. 10 üzerinden 6, ruh halini söyler. Neyi değiştireceğinizi söylemez.
Sorup sonra susmak. Bu bir sonraki turu kaybettirir, aşağıda anlatılıyor.

Bir ürün hakkındaki müşteri geri bildirimine ne denir?

Bir ürün hakkındaki geri bildirime genellikle ürün geri bildirimi denir ve iki türe ayrılır. Hata raporu bir şeyin amaçlandığı gibi çalışmadığını söyler. Özellik talebi bir şeyin eksik olduğunu söyler. Bu ayrım önce kimin bakacağına karar verir ve özellik talebi mi hata mı yazısı bu çizgiyi çizer. Üçüncü tür olan övgü, saklamaya ve izinle alıntılamaya değer.

İlk seçenek olarak "Hata" ve "Özellik talebi" sunan bir geri bildirim formu bu ilk ayrımı sizin yerinize yapar.

Cevaplarla ne yaparsınız?

Her cevabı, ekibin zaten çalıştığı yere, kişinin kendi kelimeleriyle koyun. Alıntılanmış tek bir satır, sizin özetinizden iyidir. Türüne ve kabaca aciliyetine göre etiketleyin, tekrarları birleştirin ve karar verin: yap, beklet ya da reddet.

Reddetmek de bir cevaptır. "Bunu yapmayacağız ve nedeni şu" beklemeyi bitirir ve özellik taleplerini reddetmek bunun için ifadeler sunar. Altyapı için özellik talebi takibi, beş kanaldan gelen talepleri tek bir listeye nasıl sokacağınızı anlatır. Talepleri yazılı alıyorsanız, bir özellik talebi şablonu onları karşılaştırılabilir tutar.

Changeloop'un widget'ı her gönderimi bir GitHub issue'su olarak açar, böylece geri bildirim onu düzeltecek kodun yanına düşer. Hangi araçla olursa olsun kural aynı: tek liste, tek sahip, hiçbir cevap birinin gelen kutusunda kalmaz.

Yayımlananları neden anlatmalı?

Kişiye cevap vermenin zamanına değdiğini gösterir. Size bir şey söyleyen ve sonra "bu yayımlandı, teşekkürler" cevabını alan bir kullanıcının tekrar cevap vermek için bir nedeni olur. Hiçbir şey duymayan ise kutunun okunmadığı sonucuna varır.

Yani istemenin son adımı bir cevaptır. Her isteyen kişiye, talebi yayımlandığında, kendi diliyle, kullandığı kanaldan haber verin. Müşteri geri bildirim döngüsünü kapatmak mekanizmayı anlatır: mesajı yayımlanmış changelog girdisi tetikler, böylece isteyene ancak değişiklik canlıya çıktığında haber verilir. Changeloop'ta widget geri bildirimi bir GitHub issue'su olduysa ve birleştirilen pull request onu kapattıysa, girdiyi onaylamak o issue'ya bir "Shipped" yorumu bırakır ve girdiyi widget'ta gönderene gösterir; elle açılan issue'lar ile GitLab ya da Bitbucket depoları yorum almaz. Dokümanlarımız widget ve feed kurulumunu listeler.

Cevap kısa olabilir: "Mart'ta CSV içe aktarma istemiştiniz. Bugün yayında ve nasıl çalıştığı şöyle." Ayrıca size en iyi bir sonraki soruyu verir: ihtiyacınız olanı karşılıyor mu?

Bir başlangıç planı

En üstteki tablodan bir an seçin, kullanıcıların en sık başarılı olduğu ya da vazgeçtiği anı. Onun için tek bir soru yazın, tek bir kanala koyun ve ikinci bir istem eklemeden önce iki hafta boyunca her cevabı okuyun. Size somut bir şey veren herkese cevap verin.

FAQ

Müşterilerden ne sıklıkla geri bildirim istenmeli? İstemleri takvime değil olaylara bağlayın. Bir kullanıcı haftada en fazla bir istem görmeli ve birine cevap verdikten hemen sonra hiç görmemeli. Geri bildirimden sonraki ilk mesaj, ona ne olduğuna dair bir cevap olmalı.

Kullanıcıları rahatsız etmeden geri bildirim nasıl istenir? Bir görevden sonra sorun, asla ortasında değil, tek soruya sadık kalın ve kapatmayı kolay yapın. Bir kapatmaya birkaç hafta saygı gösterin.

Geri bildirim için bir teşvik sunulmalı mı? Genellikle gerek yoktur. Somut bir soru ve görünür bir cevap, bir hediye kartından daha çok ağırlık taşır ve teşvikler ödülü isteyen insanları çeker. Onları, birinden 20 dakika istediğiniz görüşmelere saklayın.

Kimse cevap vermezse ne olur? Soruyu daraltın ve ana yaklaştırın, örneğin tek bir ekran, kullanıldıktan hemen sonra sorulsun. Sessiz kalırsa, bir avuç kullanıcıya doğrudan e-posta gönderin ve bu konuşmaları daha iyi istemler yazmak için kullanın.

Sık yayımlayan ekipler için release yönetimi süreci

Fri, 02 Oct 2026 00:00:00 GMT

Release yönetimi süreci, bir değişikliği "merge edildi"den "üretimde çalışıyor ve etkilediği insanlara anlatıldı"ya taşıyan adımlar bütünüdür. Sık yayımlayan bir ekip için yedi adıma iner: kapsamı planla, değişikliği izole et, build ve test et, onayla, deploy et ve doğrula, duyur ve gözden geçir. Her adımın belli bir sahibi ve bir çıkış ölçütü olmalı, yoksa sessizce yapılmaz olur.

Bu rehber, haftalık ya da günlük deploy eden ve sürecin yoldan çekilmesini isteyen, 5 ila 50 mühendislik ekibi varsayar.

Adım	Sahip	Çıkış ölçütü
1. Kapsamı planla	Ürün veya teknik lider	Bu release'teki değişikliklerin listesi yazılı, riskli olan her şey işaretli
2. Branch veya flag	Değişikliğin sahibi mühendis	İş kısa ömürlü bir branch'te ya da bir flag'in arkasında, main yayımlanabilir kalır
3. Build ve test	CI, hatalarda nöbetçi yazar ile	Yayımlanacak tam commit'te pipeline yeşil
4. Onayla	İnceleyici, riskli değişikliklerde release manager ile	İnceleme tamam, rollback yolu adlandırılmış, git ya da gitme kararı kaydedilmiş
5. Deploy et ve doğrula	Release manager veya nöbetçi mühendis	Deploy edildi, smoke kontrolleri geçti, hata oranı ve gecikme release öncesi referansla uyuşuyor
6. Duyur	Değişikliği anlayan, anlamayan biri tarafından düzenlenmiş	Release notes kullanıcıların okuduğu yerde yayımlandı, destek ve satışa haber verildi
7. Gözden geçir	Release manager	Metrikler okundu, ters giden her şeyin bir sahibi ve bir düzeltmesi var

Release yönetimi süreci nedir?

Bir değişikliğin kullanıcılara ulaşmak için izlediği tekrarlanabilir yoldur: kapsam, build, test, onay, deploy, doğrulama, duyuru ve geriye bakış. Yazılı hâle getirmenin amacı, her release'in aynı yolu izlemesidir; böylece tatildeki bir kişi, yeni bir çalışan ya da gece 2'deki nöbetçi mühendis, kimseye nasıl çalıştığını sormadan onu yürütebilir.

Release yönetiminin farklı türleri nelerdir?

Üç pratik tür var: sürekli deployment, zamanlanmış release'ler ve düzenlemeye tabi değişiklik yönetimi. Bir release'ten önce ne kadar şey olduğu ve ne kadarının otomatik olduğu bakımından ayrılırlar. Sürekli deployment merge edilen her değişikliği yayımlar, zamanlanmış release'ler değişiklikleri bir trene toplar ve düzenlemeye tabi değişiklik yönetimi resmi onay ve bir denetim izi ekler.

	Sürekli deployment	Zamanlanmış release'ler	Düzenlemeye tabi veya ITIL değişiklik yönetimi
Release birimi	Merge edilen tek bir pull request	Haftalık veya iki haftalık bir toplu iş	Bir değişiklik talebi
Kapsam adımı	Örtük, merge kapsamdır	Release planlama toplantısı	Risk derecesi olan değişiklik kaydı
Onay	Kod incelemesi artı otomatik kontroller	Release manager toplu işi onaylar	Değişiklik danışma kurulu veya yetkili onaylayıcı
Risk kontrolü	Feature flag'ler, canary'ler, hızlı rollback	Staging'de bekletme, release candidate	Belgelenmiş geri çekilme planı, bakım penceresi
Tipik ritim	Günde birçok	Haftalıktan aylığa	Değişiklik takvimiyle belirlenir
Zayıf nokta	Kimse kullanıcılara neyin değiştiğini söylemez	Büyük toplu işler neyin bozduğunu gizler	Süreç zamanı değişikliğin kendisini gölgede bırakır

Çoğu ekip bir karışımdır. Bir SaaS ürünü sürekli deploy ederken mobil uygulaması haftalık bir trenle çıkabilir ve denetçilerin önemsediği tek ödeme servisi resmi bir değişiklik kaydını izler. Türü şirkete göre değil servise göre seçin. Değişikliklerin sadece kademeli olarak açıldığı yerde release ve duyuru ayrı olaylara dönüşür, bu da feature flag release notları yazısının ele aldığı durumdur.

Release manager'ın sorumlulukları nelerdir?

Release manager, bir değişikliğin üretime giden yolunun sahibidir. Release takvimini tutar, bir değişikliğin hazır olup olmadığına karar verir, deploy'u yürütür ya da denetler, rollback kararını verir, kullanıcılara haber verilmesini sağlar ve sonrasındaki gözden geçirmeyi yürütür.

Release'ten önce kapsamı doğrular ve her riskli değişikliğin bir rollback yolu olup olmadığını kontrol eder. Sırasında deploy kontrol listesini yürütür, üretim metriklerinin ilk dakikalarını izler ve rollback'i erken çağırır. Sonrasında notların çıktığını doğrular ve süreçte neyin düzeltileceğini kaydeder.

Küçük bir ekipte rolü haftalık döndürün ve kontrol listesini kimsenin sözlü bilgiye ihtiyaç duymayacağı şekilde yazın. Bağımsız olarak yayımlanan birçok paketi olan bir monorepo genellikle paket başına bir release sahibi ister, yoksa rol bir darboğaza dönüşür.

Release yönetimi için temel KPI'lar nelerdir?

DORA yazılım teslimat metriklerini izleyin ve kendinizden bir tane ekleyin: kullanıcılara haber verilmesinin ne kadar sürdüğü. DORA'nın araştırması, üretim hızı (değişiklik lead time'ı, deployment sıklığı, başarısız deployment kurtarma süresi) ve kararsızlık (değişiklik başarısızlık oranı, deployment yeniden iş oranı) diye ayrılan beş metriği belirler.

DORA'nın rehberi bunları düz terimlerle tanımlar (dora.dev, software delivery metrics):

KPI	Neyi ölçer	Nelere dikkat edilir
Değişiklik lead time'ı	Sürüm kontrolündeki commit'ten üretimde deploy edilmeye geçen süre	Yükselen bir sayı genellikle incelemede ya da onayda kuyruk demektir
Deployment sıklığı	Ne sıklıkla deploy ettiğiniz ya da deployment'lar arasındaki süre	Düşen sıklık, toplu işlerin büyüdüğü anlamına gelir
Başarısız deployment kurtarma süresi	Hemen müdahale gerektiren bir deployment'tan kurtulma süresi	Rollback ve alarm sorunları burada görünür
Değişiklik başarısızlık oranı	Rollback ya da hotfix gerektiren deployment'ların payı	Toplu işler çok büyük ya da test zayıf olduğunda yükselir
Deployment yeniden iş oranı	Planlanmamış ve bir üretim olayının yol açtığı deployment'ların payı	Düzeltmelerin derslerden hızlı çıktığının işareti
Kullanıcılara haber verilene kadar süre	Üretim deploy'undan yayımlanmış, kullanıcıya dönük bir nota kadar dakika	Kendiniz ölçün, hiçbir çerçeve bunu sağlamaz

Eski kaynaklar dört anahtar sayar ve kurtarmaya "time to restore" der. Güncel rehber yukarıdaki beşini kullanır.

Aynı rehber bunları hedef olarak ele almaya karşı uyarır. "Her şey yıl sonuna kadar günde birkaç kez deploy edilsin" gibi bir hedef koymak, ekipleri sayıları oynamaya davet eder ve metriklerin şirket genelinde harmanlanmak yerine uygulama ya da servis başına okunması amaçlanır. Hepsini iyileştirmek için pratik önerisi, her değişikliğin boyutunu küçültmektir, çünkü küçük değişiklikleri incelemek, pipeline'dan geçirmek ve onlardan kurtulmak daha kolaydır.

Release iletişimi release yönetimi sürecine nasıl oturur?

Altıncı adımdır ve her diğer adım gibi bir sahibi ve bir çıkış ölçütü vardır: notlar kullanıcıların okuduğu yerde yayımlandı ve iç ekiplere haber verildi. Ekipler en sık bunu atlar, çünkü deployment araçları kod canlıya çıktığı anda başarıyı bildirir.

Bu adımı programda tutmanın en ucuz yolu, girdiyi release yayımlandığında değil, değişiklik merge edildiğinde yazmaktır. Pull request zaten başlığı, yazarı, bağlı issue'yu ve bağlamı tutar. Ondan kurulan bir taslak, bir hafta sonra hafızadan yazılmak yerine düzenlenir. Changelog otomasyonunun fikri budur: merge'de bir taslak türet, onay için bir insana beklet, sonra tek kaynaktan her yerde yayımla. Changeloop böyle çalışır: merge edilen pull request'lerden AI ile girdi taslağı hazırlar ve hiçbir şey yayımlanmadan önce onay için bekletir.

Önceden planlamaya değer iki varyasyon var. Destek ve satışın müşterilerden farklı bir nota ihtiyacı vardır, dahili release notları bunun içindir. Bir olay güdümlü release'in normal taslak döngüsüne zamanı yoktur, o yüzden acil durum release notes yazısında anlatıldığı gibi hazırda kısa bir şablon tutun. Release notes şablonu müşteriye dönük sürüm için bir başlangıç şekli verir.

Süreç nasıl hafif tutulur?

Bir makinenin kontrol edebileceği her çıkış ölçütünü otomatikleştirin ve yargı gerektiren işleri insanlara bırakın. Yeşil bir pipeline, panolarda bir deploy işareti ve merge edilen her pull request için bir changelog girdisi taslağı kontrol edilebilir. Bir rollback planının inandırıcı olup olmadığı ya da notların bir müşteriye anlamlı gelip gelmediği ise bir insan ister.

Süreci test etmek için geçen aydan bir release seçin ve ekibin dışındaki birinin sadece yazılı kayıttan neyin yayımlandığını, kimin onayladığını, nasıl doğrulandığını ve kullanıcılara ne zaman haber verildiğini söyleyip söyleyemeyeceğini sorun. Her boşluk bir sonraki iyileştirmenizdir.

FAQ

Release yönetimi ile değişiklik yönetimi arasındaki fark nedir? Release yönetimi bir değişiklik kümesinin build edilmesini, test edilmesini, deploy edilmesini ve duyurulmasını sağlar. ITIL anlamındaki değişiklik yönetimi ise her değişikliğin etrafındaki onay ve risk sürecidir. Sık yayımlayan ekipler onayı kod incelemesine ve otomatik kontrollere katar.

Ne sıklıkla release çıkarmalıyız? Testleriniz ve rollback yolunuz izin verdiği kadar sık; birçok web ekibi için bu günlük ya da daha fazladır. DORA'nın önerisi her değişikliğin boyutunu küçültmektir, çünkü küçük değişiklikleri incelemek ve onlardan kurtulmak daha kolaydır.

Küçük ekiplerin bir release manager'a ihtiyacı var mı? Sorumluluklara ihtiyaçları var, ama unvana şart değil. Rolü mühendisler arasında döndürün, nöbetteki kişiye yazılı bir kontrol listesi verin ve yedi adımın her birinin bir sahibi olduğundan emin olun.

Bir release kontrol listesi neleri içermeli? Doğrulanmış kapsam, yayımlanacak commit'te yeşil pipeline, adlandırılmış rollback yolu, kaydedilmiş onay, deploy sonrası smoke kontrolleri, metriklerin referansla karşılaştırılması, yayımlanmış release notes, bilgilendirilmiş destek ve planlanmış bir gözden geçirme. Tek bir sayfada tutun.

Ürün roadmap örnekleri: altı format ve nasıl bozulurlar

Fri, 02 Oct 2026 00:00:00 GMT

Kopyalamaya değer ürün roadmap örnekleri altı formatta toplanır: Now/Next/Later, çeyreklik zaman çizelgesi, tema roadmap'i, sonuç roadmap'i, genel roadmap ve dahili release roadmap'i. Her biri farklı bir okuyucu için farklı bir soruyu cevaplar. Yani doğru örnek, sizinkini kimin okuyacağına uyan örnektir. Yerleşim düzeni en son karar verilecek şeydir.

Aşağıdaki her örnek uydurma bir ürün, küçük bir ekip görev uygulaması içindir ve her madde hayalidir. Asıl mesele şekildir: her yuvaya ne girer, gerçek bir giriş nasıl görünür ve o format bir çeyrek sonra neden bozulur.

İyi ürün roadmap örnekleri nelerdir?

İyi bir roadmap örneği kısadır, bir okuyucuya adı verir ve tek türden söz verir. Formatı tutmaya razı olduğunuz söze göre seçin: bir yön, bir tarih, bir iş teması, bir sonuç, genel bir taahhüt ya da bir teslimat takvimi.

Format	Kimin için	Ne zaman işler	Ne zaman bozulur
Now/Next/Later	Tüm şirket	Planlar sık değiştiğinde	"Next" dolar ve bir kuyruğa dönüşür
Çeyreklik zaman çizelgesi	Satış, destek, yöneticiler	Tarihler gerçek kısıtlarsa	Tarihler kayar ve kimse güncellemez
Tema bazlı	Liderlik, yeni çalışanlar	Nedenini anlatmak istediğinizde	Temalar o kadar geniş olur ki her madde uyar
Sonuç bazlı	Ürün ve mühendislik	Hedefi ölçebildiğinizde	Metriğin sahibi ya da verisi yoktur
Genel	Müşteriler	Küçük tutabildiğinizde	Bir backlog çöplüğüne dönüşür
Dahili release	Mühendislik, QA, destek	Birkaç ekip birlikte yayımladığında	Strateji sanılır

Her ürün roadmap örneği nasıl görünür?

Aşağıdaki her format gerçekçi girdilerle gösterilir, ardından kime uyduğu, ne zaman dayandığı ve genelde nasıl bozulduğu anlatılır.

Now/Next/Later

NOW (bu ay yapılıyor)
  Gelen kutusunda kayıtlı görünümler
  Büyük hesaplarda çalışan CSV export
NEXT (karar verildi, sıra kesin değil)
  Team planı için SSO
  Slack bildirimleri
LATER (bir yön, taahhüt yok)
  Mobil uygulama
  Denetim günlüğü

Bu format tarih vermek istemeyen şirketlere uyar, ki bu birçok erken aşama ekibine denk düşer. Dayanır, çünkü üç sütun ne kadar emin olduğunuzu anlatır: "now" sürüyor, "next" karara bağlandı, "later" bir umut. Bozulması şöyle olur: "later", kimsenin reddetmek istemediği her fikrin park yerine döner ve "next" kimse zaman çizelgesi demeden sessizce bir sıra ve bir tarih edinir.

Zaman çizelgesi ya da çeyreklik roadmap

2026 Q4
  Eki   Gelen kutusunda kayıtlı görünümler
  Kas   Beş tasarım ortağıyla SSO beta
  Ara   SSO genel kullanıma açılış
2027 Q1
  Oca   Slack bildirimleri
  Mar   Denetim günlüğü (sadece export)

Bu format, bir şeye göre plan yapması gereken satış, destek ve finans ekiplerine uyar. Tarihler bir sözleşme, bir konferans ya da bir uyumluluk son tarihi gibi gerçek kısıtlar olduğunda işler. Tarihler tahmin olduğunda bozulur, çünkü roadmap'teki bir ay haftalar içinde bir satış sunumunda söze dönüşür. Bu formatı kullanıyorsanız her çeyreği "taahhüt edildi" ya da "tahmin" diye etiketleyin ve ikinci çeyreği birincisinden görünür biçimde daha yumuşak tutun.

Tema bazlı roadmap

TEMA: İlk hafta deneyimi
  CSV ve Trello'dan içe aktarma
  Başlangıç şablonları
TEMA: Büyük ekiplere hazır
  SSO
  Denetim günlüğü
  Rol izinleri
TEMA: Daha az elle yapılan adım
  Slack bildirimleri
  Tekrarlayan görevler

Bu format liderlik güncellemelerine ve yeni çalışanlara uyar, çünkü işi sıralamadan önce işin neden var olduğunu açıklar. Her tema bir müşterinin önemseyeceği bir nedene karşılık geldiğinde dayanır. Temalar o kadar genişse ("Büyüme", "Kalite") ki her madde her birinin altına sığıyor, gruplama hiçbir şey açıklamaz ve format bozulur.

Sonuç bazlı roadmap

HEDEF: Daha fazla yeni ekip kurulumu bitirsin
  Metrik: 7 günde biten kurulum, %40'tan %55'e
  Bahisler: CSV içe aktarma, başlangıç şablonları
HEDEF: Export ile ilgili daha az destek ticket'ı
  Metrik: haftalık export ticket'ı, 30'dan 10'a
  Bahisler: büyük hesap export düzeltmesi, export durum sayfası

Sayılar örnek amaçlıdır, asıl mesele düzendir: bir hedef, başlangıcı ve hedefi olan tek bir metrik ve deneyeceğiniz bahisler. Çözümü seçmesine güvenilen ürün ve mühendislik ekiplerine uyar. Metrik var olduğunda ve birinin sahipliğinde olduğunda işler. Hedef ölçülemezse ya da "bahisler" üstüne bir sonuç cümlesi yapıştırılmış eski özellik listesinin aynısıysa bozulur.

Genel, müşteriye dönük roadmap

PLANLANDI
  Gelen kutusunda kayıtlı görünümler
YAPILIYOR
  Slack bildirimleri
YAYIMLANDI
  Büyük hesaplar için CSV export

Bu en küçük formattır ve en güçlü sözü verir. İsteğinin duyulup duyulmadığını bilmek isteyen müşterilere uyar. Çok az madde, tarihsiz ve müşterinin kendi sözleriyle yazılmış başlıklarla dayanır. Backlog çöplüğü olduğunda bozulur: listelediğiniz her "belki", birinin ileride soracağı bir sözdür. Bir genel roadmap'i issue tracker'ınızdan işletmenin ayrıntıları üç sütunlu bir genel roadmap yazısında anlatılıyor, o yüzden burada tekrarlanmıyor.

Dahili release roadmap'i

Release	Hedef	Sahip	Bağımlılık	Durum
5.2	14 Eki	Platform	Auth servisi yükseltmesi	Kod tamam
5.3	11 Kas	Gelen kutusu	Kayıtlı görünümler API'si	Sürüyor
5.4	9 Ara	Platform	SSO sağlayıcı sözleşmesi	Bloke

Bu format neyin birlikte çıktığını ve neyin neyi bloke ettiğini bilmesi gereken mühendislik, QA ve destek ekiplerine uyar. Haftasına kadar doğru olduğunda ve her satırın bir sahibi olduğunda işler. Biri bunu strateji sandığında bozulur: bir teslimat takvimi neyin ne zaman binadan çıktığını söyler ve o release'lerin doğru bahisler olup olmadığı hakkında hiçbir şey söylemez.

Hangi ürün roadmap formatını seçmelisiniz?

Önce okuyucuya, sonra gerçekte ne kadar kesinliğiniz olduğuna göre seçin. Roadmap'i kimin okuduğunu ve ona hangi kararda yardım ettiğini söyleyemiyorsanız, yukarıdaki örneklerin hiçbiri onu kurtarmaz.

"Beni duydunuz mu?" diye soran müşteriler. Genel formatı kullanın ve birkaç maddede tutun.
"Müşteriye tarih söyleyebilir miyim?" diye soran satış ve destek. Çeyreklik zaman çizelgesini kullanın, taahhüt edilen ve tahmin edilenleri net ayırın.
"Neden bu iş?" diye soran liderlik. Tema kullanın, verisi varsa sonuç.
Yönünü her ay değiştiren bir ekip. Now/Next/Later kullanın ve tarih koymaya direnin.
"Ne zaman ne çıkıyor?" diye soran mühendisler. Release roadmap'ini kullanın ve stratejik olandan ayrı tutun.

Çoğu ekip ikiye varır: ilk dört şekilden birinde stratejik bir roadmap ve altında bir release takvimi. Genel roadmap o zaman stratejik olanın süzülmüş bir görünümüdür ve sadece hesabını vermeye razı olduğunuz şeyleri gösterir.

Ürün roadmap'i nasıl yazılır?

Okuyucuya ad vererek, sorusuna uyan formatı seçerek, sadece bir toplantıda savunacağınız maddeleri listeleyerek ve her maddeye bir durum ve bir sahip vererek yazın. Sonra yayımlamadan önce ne sıklıkla gözden geçirileceğine karar verin.

Okuyucuyu ve kararı adlandırın. "Destek, müşterilere SSO hakkında ne söyleyeceğine karar verir" bir gerekçedir. "Herkes roadmap'i görmeli" tasarlayacak hiçbir şey vermez.
Zaten bildiğiniz şeyden başlayın. Açıklayabileceğiniz bir kurala göre sıralanmış açık talepler, bir beyin fırtınasından daha iyi ham maddedir.
Her maddeyi bir müşteri sonucu olarak yazın. "Sık kullandığınız bir filtreyi saklayın", "Kayıtlı görünüm kalıcılığını uygula" cümlesinden daha iyi okunur ve müşteriye bunun kendi sorunu olup olmadığını söyler.
Roadmap'in neyi içermeyeceğine karar verin. Tarihler, tahminler ve bir fikir backlog'u üç olağan dışarıda bırakılandır.
Bir gözden geçirme tarihi koyun. Planlı gözden geçirmesi olmayan bir roadmap'in planlanmamış bir cenazesi olur.

Ürün roadmap'i nasıl güncel tutulur?

İş hareket ettiğinde, işin takip edildiği yerden maddeleri taşıyarak ve bir madde yayımlandığında ya da bırakıldığında ne olduğunu kaydederek güncel tutun. Ayrı bir araçta elle güncellenen roadmap bayatlar, çünkü kimsenin günlük işi değildir.

En ucuz doğruluk kaynağı issue tracker'dır. Her roadmap sütunu issue üzerindeki bir etikete karşılık geliyorsa, etiket değiştiğinde roadmap değişir ve hiçbir şey yeniden yazılmaz. Changeloop'un bu yaklaşımı roadmap:planned, roadmap:building ve roadmap:shipped etiketlerini kullanır ve bir issue ikisini birden taşıdığında en ileride olan kazanır. Bir kartı yayımlandıya taşımak yine kendi etiket değişikliğidir, o yüzden changelog girdisini onayladığınız gözden geçirmenin bir parçası yapın.

Bu girdi diğer yarıdır. Bir madde yayımlandığında changelog neyin değiştiğini müşterinin diliyle söyler ve isteyen birine haber verilebilir. Bu döngüyü kapatmak müşteri geri bildirim döngüsünün amacıdır ve roadmap, bu döngünün hiçbir şey yayımlanmadan önce müşterinin görebildiği kısmıdır. Bir maddeyi bırakırsanız bunu söyleyin; genel bir "hayır" o talebi de kapatır ve özellik taleplerini reddetmek yazısı bunu nasıl ifade edeceğinizi anlatır. Biten girdilerin nasıl okunduğunu görmek isteyen ekipler changelog örneklerine göz atabilir.

FAQ

En basit ürün roadmap formatı nedir? Now/Next/Later. Üç sütunu vardır, tarih gerektirmez ve maddeleri kesinliğe göre gruplar. Yönünü sık değiştiren küçük bir ekip için, utanç verici biçimde yanlış yapılması en zor formattır.

Bir ürün roadmap'inde kaç madde olmalı? Sandığınızdan az. Genel bir roadmap için tüm sütunlarda on maddenin altı yeter, dahili stratejik olana nadiren on iki taneden fazlası gerekir. Bunun ötesi, daha güzel bir başlığı olan bir backlog'dur.

Bir ürün roadmap'i tarih içermeli mi? Sadece tarihler gerçek kısıtlarsa ve o zaman da sadece en yakın çeyrek için. Ötesinde sütun ya da tema kullanın. Roadmap'teki bir tarih, siz istemeseniz de bir satış görüşmesinde taahhüde dönüşür.

Ürün roadmap'i ile release planı arasındaki fark nedir? Roadmap neyi neden inşa etmeyi amaçladığınızı söyler. Release planı hangi build'in hangi tarihte, kimin sorumluluğunda çıktığını söyler. Roadmap stratejiniz değiştiğinde, release planı iş değiştiğinde değişir.

Her değişiklik türü için release notes örnekleri

Fri, 02 Oct 2026 00:00:00 GMT

En iyi release notes örnekleri kısadır, kimin etkilendiğini söyler ve sonra ne yapılacağını belirtir. Aşağıda yayımlayacağınız her değişiklik türü için, neden işe yaradığıyla birlikte bir örnek var; böylece şekli kopyalayıp kendi bilgilerinizi koyabilirsiniz.

Her örnek, Tidepool adında hayali bir faturalama uygulaması için uydurulmuştur.

İyi release notes örneklerinin ortak yanı nedir?

Kullanıcılara neyin değiştiğini ve bu konuda bir şey yapmaları gerekip gerekmediğini, kullanıcıların kendi kelimeleriyle söylerler. Her değişiklik türünün farklı bir işi var, o yüzden şekil bunlar arasında kayar.

Değişiklik türü	Girdi şunu söylemeli	Nereye gider
Yeni özellik	Okuyucu artık ne yapabiliyor ve kim alıyor	Notların en üstü
İyileştirme	Neyin hızlandığı ya da kolaylaştığı, varsa bir sayıyla	Özelliklerden sonra
Hata düzeltmesi	Okuyucunun gördüğü belirti ve düzeldiği	İyileştirmelerden sonra
Breaking change	Kim etkileniyor, tarih, geçiş	Her zaman ilk
Güvenlik düzeltmesi	Neyin açıkta kaldığı, istismar edilip edilmediği, ne yapılacağı	İlk
Deprecation	Neyin kalktığı, bitiş tarihi, yerine ne geldiği	Üste yakın
Mağaza notu	Her değişiklik için bir düz cümle, karakter sınırı içinde	Mağaza sayfası
Dahili not	Neyin değiştiği ve müşterilere ne söyleneceği	Destek ve satış kanalları

İyi bir yeni özellik notu nasıl görünür?

İyi bir özellik notu, okuyucunun artık ne yapabildiğiyle açılır ve onu alan planları ya da rolleri adlandırır. Uygulamayı atlar.

Faturaları müşterinin dilinde gönderin. Artık her müşteri için bir dil seçebilirsiniz ve faturaları, hatırlatmaları ve ödeme sayfası ona uyar. Fransızca, Almanca, İspanyolca ve Portekizce tüm planlarda mevcut. Müşterinin sayfasında Faturalama tercihleri altından ayarlayın.

Başlık okuyucunun yüksek sesle söyleyeceği bir ifadedir ve gövde kapsamı ve yeri verir. Sadece kalın satıra göz atan okuyucu yine de neyin yayımlandığını bilir. Daha geniş yöntem release notes nasıl yazılır yazısında.

İyi bir iyileştirme notu nasıl görünür?

İyileştirme notu, okuyucunun hissedeceği bir değişikliği anlatır ve varsa üzerine ölçülmüş bir sayı koyar. Sayı yoksa, okuyucunun artık yapmak zorunda olmadığı şeyi söyleyin.

Fatura listesi yaklaşık üç kat daha hızlı açılıyor. 5.000'den fazla faturası olan hesaplar liste için yaklaşık dokuz saniye beklerdi. Artık yaklaşık üç saniyede açılıyor. Hiçbir işlem gerekmiyor.

"Performans iyileştirmeleri" okuyucuya hiçbir şey söylemez, dokuza karşı üç saniye ise pazartesi sabahı kontrol edebilecekleri bir iddiadır. Kapanıştaki "Hiçbir işlem gerekmiyor" her okuyucunun sorduğu soruyu cevaplar.

İyi bir hata düzeltmesi notu nasıl görünür?

Hata düzeltmesi notu, koddaki nedeni değil kullanıcının gördüğü belirtiyi anlatır ve bir şeyi yeniden yapmaları gerekip gerekmediğini söyler. Kimsenin fark etmediği düzeltmeler en alttaki listeye girebilir.

Düzeltildi: hatırlatma e-postaları vade gününde iki kez gönderiliyordu. Bazı müşteriler, faturaları bir ayın son gününe denk geldiğinde iki özdeş hatırlatma aldı. Bu düzeltildi. Daha önce gönderilen hatırlatmalar etkilenmiyor ve kimsenin bir şeyi yeniden göndermesi gerekmiyor.

Başlık "Düzeltildi" ile başlar, böylece göz gezdiren biri bir bakışta ayırabilir ve gerçek koşul (ayın son günü) hemen arkasından gelir.

Breaking change için release notes nasıl yazılır?

Breaking change notu tarihle ve etkilenen grupla açılır, sonra geçişi aynı girdide verir. Release notes'ta ilk sıraya gider, çünkü okuyucunun kaçırmaması gereken tek girdidir.

Webhook imzaları 1 Aralık 2026'da zorunlu oluyor. O tarihten itibaren Tidepool imzasız webhook payload'ları göndermeyi bırakıyor. Bu, webhook'ları Tidepool-Signature header'ını doğrulamadan alan herkesi etkiliyor. Geçmek için header'ı, Ayarlar, Geliştiriciler altındaki sır ile doğrulayın. İmzaları zaten doğruluyorsanız, hiçbir işlem gerekmiyor.

Tarih başlıktadır, böylece göz gezdirmeye dayanır. Etkilenen grup yaptığı işle adlandırılır ve son cümle zaten sorunsuz olanları serbest bırakır, bu da destek yükünü azaltır. Breaking change'ler rehberi, bir değişikliğin breaking sayılıp sayılmayacağına nasıl karar verileceğini anlatır.

Bir güvenlik düzeltmesi notu neye benzer?

Güvenlik notu neyin açıkta kaldığını, birinin istismar edip etmediğini, kimin etkilendiğini ve ne yapmaları gerektiğini söyler. Olgusal ve sakin tutun.

Güvenlik: parola sıfırlama bağlantıları yeniden kullanılabiliyordu. 3 ile 17 Eylül 2026 arasında, bir parola sıfırlama bağlantısı bir kez kullanıldıktan sonra da geçerli kalıyordu. İstismar edildiğine dair bir iz bulmadık. Düzeltildi ve bekleyen tüm sıfırlama bağlantıları geçersiz kılındı. O aralıkta bir sıfırlama istediyseniz, yeni bir bağlantı isteyin.

Kesin aralık okuyucunun kendi maruziyetini değerlendirmesini sağlar ve istismar hakkındaki cümle, herkesin sorduğu ilk soruyu cevaplar. "Olası bir sorun" gizleme gibi okunur, o yüzden bildiğinizi söyleyin.

Deprecation bildirimi nasıl yazılır?

Deprecation bildirimi neyin kaldırıldığını adlandırır, kesin bir bitiş tarihi verir ve yerine geçeni gösterir.

v1 faturalar endpoint'i deprecated oldu ve 1 Mart 2027'de sona eriyor. GET /v1/invoices 1 Mart 2027'ye kadar çalışmaya devam eder, sonra 410 Gone döndürür. Aynı alanları artı currency döndüren GET /v2/invoices kullanın. v1'den dönen yanıtlar artık bitiş tarihini içeren bir Sunset header'ı taşıyor. Yan yana bir geçiş kılavuzu dokümanlarda.

Endpoint adı başlıktadır, çünkü etkilenenler onu arar ve yerine geçen kaldırılanın yanında durur. Sunset header'ı geliştiricilere hangi çağrıların hâlâ eski sürümü kullandığını söyler. Daha uzun anlatım bir API'yi deprecate etmek yazısında.

Mağaza release notu nasıl görünür?

Mağaza notu iki ya da üç düz cümledir, çünkü çoğu insan sadece ilk satırı okur. Kullanıcının fark edeceği değişiklikle başlayın.

Kâğıt bir fişi tarayın, Tidepool tutarı, tarihi ve satıcıyı doldursun. Karanlık mod artık telefon ayarınızı izliyor. Ayrıca bir bildirimden fatura açarken oluşan bir çökmeyi düzelttik.

En yararlı değişiklik ilk sırada ve düzeltme, çöken durumu adlandırır. Sürüm numarası ve "hata düzeltmeleri ve iyileştirmeler" yok. Mobil uygulamalar için release notes mağazaya özgü kuralları ele alır.

Dahili release notu neleri içermeli?

Dahili not, destek ve satış için olan sürümdür. Herkese açık notun dışarıda bıraktığını ekler: ne söylenecek ve neyin vaat edilmeyeceği.

Çok dilli faturalar bugün yayımlandı (tüm planlar). Destek: müşteriler dili Faturalama tercihleri altından ayarlıyor ve mevcut faturalar özgün dillerini koruyor. İtalyanca henüz mevcut değil. Satış: bu her plana açık, o yüzden onu bir yükseltme olarak konumlandırmayın.

Her hedef kitle kendi etiketli satırını alır ve not sınırı ("İtalyanca henüz mevcut değil") bir müşteri sormadan önce çizer. Dahili release notları makalesi biçimi ve kanalları ele alır.

Kötü bir release notu nasıl görünür, yeniden yazılmış hâliyle?

Kötü bir release notu, okuyucunun ne aldığını değil ekibin ne yaptığını listeler. Sonucu öne alıp dahili sözlüğü silerek düzeltin.

Önce:

v3.8.1 Hatırlatma zamanlayıcısı refactor edildi. ReminderJob'daki race condition düzeltildi. bull 4.12'ye güncellendi. Çeşitli iyileştirmeler.

Sonra:

Hatırlatma e-postaları artık iki kez gitmiyor. Faturası bir ayın son gününe denk gelen müşteriler iki hatırlatma alabiliyordu. Bu düzeltildi ve daha önce gönderilen hatırlatmaların yeniden gönderilmesi gerekmiyor. Hiçbir işlem gerekmiyor.

3.8.1'de ayrıca: bull 4.12'ye güncellendi.

Bağımlılık güncellemesi bir alt bilgi satırına indi ve race condition, bir müşterinin tanıyacağı bir belirtiye dönüştü.

Release notes sürümler arasında nasıl tutarlı tutulur?

Her girdiyi değişiklik merge edildiğinde taslak olarak yazın ve yayımlanmadan önce bir insana onaylatın.

Changeloop böyle çalışır: merge edilen her pull request'ten AI ile bir girdi taslağı hazırlar ve onaylanması için bir insana bekletir. Onay adımı, bir editörün yukarıdaki kuralları uyguladığı yerdir. Önce biçime karar vermek için release notes şablonundan başlayın, bitmiş sayfaların nasıl göründüğü için de changelog örneklerine bakın.

FAQ

Yeni release notes nedir? Yeni release notes, bir ürünün son sürümüyle birlikte yayımlanan, neyin değiştiğini ve kullanıcıların ne yapması gerektiğini anlatan mesajdır. Özellikleri, iyileştirmeleri, düzeltmeleri ve breaking change'leri kapsar.

Release note ile changelog arasındaki fark nedir? Changelog her şeyi tutar, tam geçmişi isteyen herkes için. Release note ondan seçer: tek bir sürüm, sürümün kendilerini ilgilendirip ilgilendirmediğine karar veren okuyucular için yazılmış. Daha ayrıntılı karşılaştırma changelog vs release notes yazısında.

Release notes ne anlama gelir? Release notes, kullanıcılara bir sürümde neyin değiştiğini anlatır. İfade, bir uygulama mağazasındaki "Yenilikler" metninden bir şirket sitesindeki bir sayfaya kadar, neyin yayımlandığını açıklayan her şeyi kapsar.

Her release note girdisi ne kadar uzun olmalı? Çoğu girdi için iki ila dört cümle yeter: sonuç, kimin etkilendiği ve ne yapılacağı. Bir breaking change ya da güvenlik düzeltmesi, bir tarih ya da geçiş gerektirdiği için daha uzun sürebilir.

Stripe API versiyonlama: nasıl çalışır, neler kopyalanır

Fri, 02 Oct 2026 00:00:00 GMT

Stripe API versiyonlama tarihe göre çalışır. Her hesap, bir yayın tarihinden adını alan bir API sürümüne sabitlenir ve tek tek her istek bu sabitlemeyi bir Stripe-Version header'ıyla ezebilir. Bu yazı sırasında (Ekim 2026), Stripe dokümanlarındaki güncel sürüm 2026-09-30.endive ve aynı şemayı çok daha küçük bir API bir hafta sonunda kopyalayabilir.

Aşağıdaki her Stripe olgusu Stripe'ın kendi sayfalarından gelir ve kullanıldığı yerde bağlantılıdır.

Mekanizma	Stripe ne yapıyor	Kaynak
Sürüm adı	Bir tarih, 2024'ten beri bir release adı da (`2026-09-30.endive`)	Versioning
Varsayılan sürüm	Hesaba sabitlenir, Workbench'te değiştirilir	Versioning
İstek başına ezme	`Stripe-Version` header'ı ya da SDK seçeneği	Upgrades
Webhook'lar	Endpoint'te ayarlanan sürümde işlenir	Upgrades
Ritim	Breaking change içermeyen aylık release'ler, yılda iki major release	Versioning
Eski sürümler	Dahili sürüm değişikliği modülleriyle çalışır tutulur	Engineering post

Stripe API versiyonlama nasıl çalışır?

Stripe her hesaba varsayılan bir API sürümü verir ve bir sürüm adlandırmayan her istek onu kullanır. Çağıranlar ne zaman geçeceklerini, varsayılanı değiştirerek ya da tek tek isteklerde bir sürüm ayarlayarak seçer.

Stripe'ın mühendislik yazısına göre hesap, ilk API isteğini yaptığında sabitlenir: hesap "automatically pinned to the most recent version available" olur ve o andan sonra her çağrıya bu sürüm örtük olarak atanır.

Sürüm dizesi bir tarihtir. 2024-09-30.acacia release'inden beri bir ad da taşır, 2026-09-30.endive örneğindeki gibi. Tarih sürümleri sıralar, ad ise bir sürümün hangi major release ailesine ait olduğunu söyler.

İstek başına sürüm nasıl seçilir?

İstekte Stripe-Version header'ını gönderin ya da sürümü SDK'da ayarlayın. Stripe'ın yükseltme rehberi header biçimini gösterir ve aynı çağrı canlı ve test ortamlarında çalışır.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

Stripe'ın rehberi, sürümü bir SDK'da global olarak ya da istek başına ayarladığınızda yanıt nesnelerinin o sürümde döndüğünü not eder.

Stripe ayrıca hesap varsayılanına yaslanmamayı önerir. Kendi sözleriyle, kodunuz sürüme karar versin ve bir panel ayarı vermesin diye, her istek için header ile ya da sabitlenmiş bir SDK ile sürümü belirtin.

SDK'lar dile göre farklı sabitlenir. Dokümanlar, dinamik tipli kütüphanelerin son sürümlerinin o SDK release'i yayımlandığında en güncel olan API sürümünü kullandığını, güçlü tipli olanların (Java, Go ve .NET) ise ona sabitlendiğini söyler. Bir kütüphane sürümünü kurmak, fiilen bir API sürümü seçmektir.

Sürüm değiştiğinde webhook'lara ne olur?

Bir webhook olayı, sunucu kodunuzun kullandığı sürümde değil, endpoint'ine bağlı API sürümünde işlenir. Stripe'ın dokümanları, olayların endpoint oluşturulurken ayarlanan sürümü, yoksa hesap varsayılanını kullandığını söyler. SDK sürümünüzü değiştirmek webhook handler'ınızın aldığını değiştirmez.

Bu yüzden istek yolunuz ve olay yolunuz iki farklı sürümde durabilir. Olay hedefleri için snapshot_api_version'ı sadece hedefi oluştururken ayarlarsınız, yani farklı bir sürüm yeni bir hedef demektir.

Stripe'ın buradaki yükseltme yolu paralel bir çalıştırmadır. Hedef sürümde yeni bir endpoint oluşturun, aynı olayları ikisine de gönderin, handler'a birini işlemeyi ve diğerini yok saymayı öğretin, sonra geçin ve eski endpoint'i devre dışı bırakın. Çakışma süresince her olay iki kez geldiği için handler idempotent olmalıdır. Bu, olay yayan her API için kopyalanacak iyi bir kalıptır ve gerektiren payload değişikliklerini duyurduğunuz yer bir webhook changelog'u olur.

Aylık ve major release'ler nedir?

2024-09-30.acacia release'inden beri Stripe aylık olarak breaking change içermeyen yeni bir API sürümü yayımlar ve yılda iki kez, breaking change içeren bir sürümle başlayan yeni bir major release çıkarır. Versioning sayfası, herhangi bir aylık release'e kodunuzu güncellemeden yükseltebileceğinizi, bir major release'in ise değişiklik gerektirebileceğini söyler.

Major release'ler ad taşır. Versioning sayfası örnek olarak Basil'i verir ve Stripe'ın süreç duyurusu, adların bitkilerden geldiğini, Acacia ile başladığını ve aylık release'lerin kendilerinden önceki major release'in adını koruduğunu, böylece adın yükseltmenin güvenli olduğunu işaret ettiğini söyler. Stripe'ın changelog'u kullanımdaki adları listeler ve bu yazı sırasında en yeni girdi 2026-09-30.endive'dir.

Yani tarih "ne kadar yeni" sorusunu, ad ise "bu bir breaking sınırı mı" sorusunu cevaplar. Stripe'ın duyurusu istisnalara da yer bırakır: bir entegrasyonun onsuz ciddi biçimde etkileneceği yerde döngü dışı bir breaking change yayımlama hakkını saklı tutar. Duyuru Stripe's new API release process adresinde.

Stripe API'nin son sürümü nedir?

Bu yazı sırasında (Ekim 2026), Stripe'ın versioning sayfası güncel sürümün 2026-09-30.endive olduğunu söyler ve changelog'u aynı sürümü en yeni olarak listeler. Stripe her ay yeni bir sürüm yayımlar, bu yüzden bir makalede basılı her dize hızla eskir. Bir şeyi sabitlemeden önce canlı changelog'u okuyun ve test ettiğiniz sürümü sabitleyin.

Stripe eski sürümleri nasıl çalışır tutuyor?

Stripe, her breaking change'i kendi içinde tamamlanmış bir sürüm değişikliği modülü olarak yazarak ve modülleri verinin en yeni biçiminden geriye doğru uygulayarak eski sürümleri canlı tutar. API versiyonlama üzerine mühendislik yazısı mekanizmayı anlatır.

Her modül neyi değiştirdiğini bildirir, değişikliği belgelendirir ve bir dönüşüm fonksiyonu içerir. Yazı, bir alanın string'den hash'e değişmesi örneğini verir. Bir yanıt oluşturmak için sistem hedef sürümü bulur, sonra zamanda geriye yürür ve o sürüme varana kadar yol boyunca bulduğu her modülü uygular.

Bu tasarımdan iki yan etki doğar ve yazı ikisini de adlandırır. Modüller dokunduğu alanları ve kaynakları bildirdiği için Stripe, API changelog'unu dağıtım sırasında onlardan üretebilir. Hesabın sürümü bilindiği için de dokümantasyon ona uyum sağlayabilir ve o sürümden beri geriye uyumsuz değişiklikler hakkında uyarabilir.

Maliyeti nedir ve küçük bir API ne kopyalamalı?

Versiyonlama mühendislik dikkati maliyeti taşır ve Stripe bunu söyler. Mühendislik yazısı bir bakım yükünü kabul eder ve yeni kod yazarken eski davranış için ne kadar az düşünmek gerekirse o kadar iyi olduğu hedefini belirtir. Ayrıca hiç sürüm değişikliği gerektirmemek için release öncesi hafif API incelemelerini de anlatır.

Küçük bir API her eski sürüm için bir modül zincirini karşılayamaz ve buna ihtiyacı da yoktur. Değeri taşıyan parçaları kopyalayın:

Tarihli sürümler. Bir tarih, neyin "major" sayıldığına dair yargı gerektirmez ve çağıranlar onu okuyabilir. Versiyonlama en iyi uygulamaları makalesi bunu URL ve header şemalarıyla karşılaştırır.
Sabitlenmiş bir varsayılan. Hesabı ya da anahtarı ilk kullanımda sürüme sabitleyin, böylece API çalışan bir entegrasyonun altından kaymaz.
İstek başına bir ezme. Çağıranın yeni bir sürümü, taahhüt etmeden önce tek bir çağrıda, canlıda test etmesini sağlayan bir header.
Webhook endpoint'inde bir sürüm. Olay payload'ları, çağıranların en çok şaşırdığı yerdir.
Sürüm başına bir changelog girdisi. Sürümü, tarihi, kimin etkilendiğini ve ne yapılacağını adlandırsın. Neyin breaking sayıldığı, yeni bir sürüme neyin ait olduğunun testidir ve API changelog makalesi girdinin kendisini ele alır.

Desteklenen sürüm sayısı sizi zorlayana kadar modül zincirini atlayın. İki ya da üç canlı sürüm birkaç dal ve bir sunset tarihiyle idare edilebilir; bunu bir API sürümünü kapatmak yazısı adım adım anlatır.

Tarihli bir changelog yayımlıyorsanız, sürüm geçmişi girdileri kadar iyidir. Changeloop'ta her merge edilen pull request'ten bir girdi taslağı hazırlanır ve changelog sayfasına ve feed'e yayımlanmadan önce bir insanın onaylaması için bekletilir. Sürüm başına girdi orada yazılır ve tek insan kapısı, çağıranın ne yapması gerektiğini söyleyen gözden geçirmedir.

FAQ

Stripe API'nin son sürümü nedir? Bu yazı sırasında (Ekim 2026), Stripe'ın versioning sayfası güncel sürümün 2026-09-30.endive olduğunu söyler. Stripe her ay yeni bir sürüm çıkarır, bu yüzden sabitlemeden önce changelog'una bakın ve hesap varsayılanına yaslanmak yerine sürümü kodunuza yazın.

Bir istekte Stripe API sürümünü nasıl ayarlarım? Stripe-Version header'ını gönderin, örneğin Stripe-Version: 2026-09-30.endive, ya da sunucu tarafı SDK'nızda sürümü global olarak veya istek başına ayarlayın. İkisi de yoksa istek, Workbench'te sizin ayarladığınız hesabınızın varsayılan sürümünü kullanır.

Webhook'lar isteklerimle aynı Stripe API sürümünü kullanır mı? Mutlaka değil. Webhook olayları endpoint oluşturulurken ayarlanan sürümü, hiçbiri ayarlanmadıysa hesap varsayılanını kullanır. SDK'nızı yükseltmek webhook handler'ınızın aldığı payload'ı değiştirmez, bu yüzden endpoint'leri ayrı yükseltin ve paralel test edin.

Stripe tarzı tarihli versiyonlama küçük bir API için doğru mu? Tarihli sürümler, sabitlenmiş bir varsayılan, istek başına bir header ve sürüm başına bir changelog girdisi ucuzdur ve kopyalamaya değer. Aynı anda birçok eski sürümü desteklemediğiniz sürece, sürüm değişikliği modüllerinin iç zinciri öyle değildir. İki canlı sürümle ve eskisi için bir sunset tarihiyle başlayın.

Changelog'u kim yazar, kim yazmalı

Tue, 22 Sep 2026 00:00:00 GMT

Bir ekibe changelog'u kimin yazdığını sorun ve dürüst cevap genellikle "kim hatırlarsa" olur, ki bu CI'da bir changelog kaydını zorunlu kılmak'ın mekanik seviyede düzeltmek için var olduğu aynı başarısızlık modudur. Ama bir kaydın var olmasını zorlamak, kimin onu iyi yazmak için nitelikli olduğuna karar vermez, ve bu soruyu atlayan ekipler genellikle zorlaması en kolay olana, genellikle PR yazarına, bunun gerçekten onu iyi yazabilecek kişi olup olmadığını kontrol etmeden varsayılan olarak yönelir.

PR yazarı neden otomatik olarak en iyi changelog yazarı olmuyor?

Çünkü uygulamayı bilir, illa etkiyi değil, ve bunlar farklı bilgi türleridir. Conventional commits nerede durur, bu boşluğu commit mesajı tarafından ele alır: fix(auth): reject expired refresh tokens doğrudur ve bir müşteriye hiçbir şey söylemez, ve o düzeltmeyi yazan kişi genellikle onu çevirmek için en az donanımlı kişidir, çünkü saatlerdir hata açısından düşünmüştür ve bir kullanıcının gerçekte ne yaşadığına dair dışarıdan görüşü kaybetmiştir. Bu, teknik yazarlığın bir meslek olarak var olmasının aynı nedenidir: uygulamayı etkiye çevirmek, o şeyi inşa etmiş olmaktan farklı bir beceridir, ve mühendis kodda ne kadar iyi olursa olsun pratik gerektirir.

Bu, ürün veya destek ekibinin her kaydı onun yerine yazması gerektiği anlamına mı gelir?

Hayır, çünkü onların ters bir boşluğu vardır: kullanıcılar için neyin önemli olduğunu bilirler ama her zaman gerçekte neyin gönderildiğini bilmezler, ki bu okunabilir ama kapsamda arada sırada yanlış kayıtlar üretir, hâlâ bir flag'in arkasında olan bir özellik için "artık X'i destekliyor" iddiası, veya üç durumdan sadece birini kapsarken tam olarak tarif edilen bir düzeltme. Mühendis-yazılı kayıtların başarısızlık modu okunamaz-ama-doğru'dur; PM-yazılı kayıtların başarısızlık modu okunabilir-ama-doğrulanmamış'tır. Hiçbir rol, iyi bir kaydın ihtiyaç duyduğu iki yarının ikisine de sahip değildir.

Rol	Genellikle doğru yapar	Genellikle yanlış yapar
Kodu yazan mühendis	Neyin değiştiğinin tam kapsamı	Onu inşa etmeyen biri için çerçeveleme
PM veya destek lideri	Kullanıcı için neden önemli olduğu	Gerçekte neyin gönderildiğinin kesin sınırları
Adanmış changelog sahibi	Tutarlı ses, kapsamı çapraz kontrol eder	Karşı kontrol için yukarıdaki ikisine de ihtiyaç duyar

Çalışan bir sahiplik modeli gerçekte neye benziyor?

Değişikliğe en yakın olandan bir taslak, kullanıcıya en yakın olan tarafından incelenmiş, herkesin başka birinin sorunları yakalayacağını varsaymak yerine son ifadeden sorumlu isimlendirilmiş bir kişiyle. Taslağın iyi olmaktan çok var olması ve doğru olması gerekir; neyin değiştiğini doğru söyleyen mühendis-yazılı kaba bir cümle, cilalı ama doğrulanmamış bir cümleden daha iyi bir başlangıç noktasıdır, çünkü netlik için yeniden yazmak doğruluk için yeniden yazmaktan daha kolaydır. İnceleme adımı, bir PM veya destek liderinin taslağı okuyup okunabilirlik boşluğunu yakalayan tek soruyu sorduğu yerdir: kodu görmeseydim bunu anlar mıydım.

Sorumlu kişi her zaman aynı mı olmalı, yoksa rotasyon mu olmalı?

En azından son onay için isimlendirilmiş ve sabit, rotasyona kıyasla kazanır. Rotasyonlu bir sahip, her kaydın ekibin geleneklerini sıfırdan yeniden türeten biri tarafından incelendiği anlamına gelir, ki bu tam olarak sesin kayıttan kayda kaymasının ve bir okuyucunun changelog'un bir komite tarafından yazıldığını fark etmeye başlamasının yoludur. Tek bir kişi, veya çok küçük sabit bir grup, zamanla yargı çağrılarını biriktirir, ne zaman "iyileştirildi" demek ne zaman belirli sayıyı adlandırmak arasında, ne zaman bir düzeltmenin kendi kaydına ihtiyaç duyduğu ne zaman bir grupla katlanacağı arasında, ve o yargı işi eşit dağıtmaktan daha değerlidir.

Taslak (mühendis, PR'dan):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

İncelendi (changelog sahibi, gerçek PR'a karşı kontrol edildi):
"Düzeltildi: tarihe göre sıralanan export'lar ilk sayfanın
ötesinde sırasız sonuçlar döndürebiliyordu. Artık tüm
sayfalarda tutarlı."

Küçük bir ekip bir satır metin için bu kadar sürece ihtiyaç duyar mı?

Ayrı kişiler olarak roller değil, ama iki adım tek başına bile hâlâ önemlidir. Bir kişilik bir ekip hem mühendis hem de incelemecidir, ve bu ölçekte hayatta kalan disiplin, incelemeyi ayrı bir zihinsel geçiş olarak yapmaktır, düzeltmeyi yazmaktan onu aynı nefeste yayımlamaya doğrudan atlamak değildir. Küçük ölçekteki tuzak, ikinci bir kişinin eksikliği değil, hiçbir dış güç zorlamadığı için ikinci geçişi tamamen atlamaktır, ve o geçişin yakalamak için var olduğu doğruluk boşluğu, aynı kişinin teorik olarak kendi kör noktasını fark edebileceği için ortadan kalkmaz.

Son kayıttan kimse sorumlu olmadığında ne olur?

Changelog tamamen başarısız olmak yerine düzensiz şekilde bozulur, ki bu daha kötüdür çünkü bir okuyucu bunu işaret edene kadar kimse fark etmez. Bazı kayıtlar keskin kalır çünkü onları yazan kişi umursamıştır; diğerleri belirsizleşir, "çeşitli iyileştirmeler ve hata düzeltmeleri", çünkü onları yazan kişi hızlı hareket ediyordu ve kimse yayımlanmadan önce bunu yakalamadı. Keep a Changelog'ın format kısıtlamaları yapısal kaymayı yakalar, eksik tarihler, yanlış kategoriler, ama hiçbir şablon teknik olarak iyi biçimlendirilmiş belirsiz bir kaydı yakalamaz, ki bu tam olarak isimlendirilmiş bir sahibin kapatmak için orada olduğu boşluktur.

FAQ

Changelog sahibi bir mühendislik mi yoksa ürün rolü mü olmalı? Kişi hem kapsamı doğrulamak için teknik akıcılığa hem de dışarıdan bir okuyucu için yazacak kadar uygulamadan mesafeye sahipse ikisi de işe yarayabilir; unvan, ikisini de yapıp yapamadığından, veya yapamadığı yarı için kime sorması gerektiğini bilip bilmediğinden daha az önemlidir.

Changelog sahipliği için rotasyonlu bir nöbetçi tarzı program hiç uygun mudur? Hacim için bazen, ekip bir kişinin her şeyi incelemesi için çok küçükse; ses ve yargı için hayır, çünkü rotasyonun aşındırdığı tam olarak budur. Yazma yükünü paylaşırken sabit bir incelemeciyi koruyan bir rotasyon, kaymadan faydayı elde eder.

Mevcut sahiplik yapısında bir şeylerin yanlış olduğunun en hızlı işareti nedir? Kim yazdığını izleyen bir kalıpta, doğru ama okunamaz, veya okunabilir ama kapsamda yanlış kayıtlar. Kalite tutarlı kalmak yerine yazarla ilişkiliyse, boşluk sahipliktir, yazma becerisi değildir.

Otomasyon sahipliğin ne kadar önemli olduğunu azaltır mı? Ne kadar yazmaya ihtiyaç olduğunu azaltır, ne kadar yargıya ihtiyaç olduğunu değil. Changelog otomasyonu, bir pipeline'ın güvenle üretebileceklerini ele alır, biçimlendirme, yayınlama, çapraz gönderim; ifade, gruplandırma ve bahsetmeye değer sayılan şey, pipeline'ın ne kadarı otomatikleştirilmiş olursa olsun insan kararları olarak kalır.

PR yazarı ile inceleyen kişi ifade konusunda anlaşamazsa ne olur? Karar inceleyen kişiye aittir, çünkü cevapladığı soru, dışarıdan bir okuyucu bunu anlar mıydı, rolün korumak için var olduğu sorudur. Bu, mühendisin okumasını değersiz kılmaz: anlaşmazlık ifadeden çok doğruluk hakkındaysa, inceleyen kişi geri çekilir, çünkü kapsamı doğru almak yazarın yarısıdır. İki tür anlaşmazlığı, ifade ile doğruluk, ayırmak bunların çoğunun çıkmaza dönüşmesini engeller.

Acil durum release notes: zaman baskısı altında yazmak

Tue, 22 Sep 2026 00:00:00 GMT

Çoğu release notes, kod bittikten sonra rahatça gözden geçirilerek ve kimsenin onları ne kadar aciliyetle okuması gerektiğiyle hiçbir ilgisi olmayan bir programa göre yayımlanarak yazılır. Bir acil durum sürümü, bir güvenlik yaması, bir veri kaybı hatası, bir kesinti düzeltmesi, bu koşulların her birini aynı anda tersine çevirir: notlar, çoğu insanın normalde yazmaya başlayacağı zamandan önce var olmalı, neredeyse hiç inceleme almaz, ve rahat değil endişeli insanlar tarafından okunur. Release notes nasıl yazılır normal süreci ele alır; bu, onu takip etmek için zaman kalmadığında neyin değiştiğiyle ilgilidir.

Başka hiçbir şeyi doğru yapmasa da bir acil durum release notu'nun mutlaka doğru yapması gereken tek şey nedir?

Okuyucunun bir şey yapması gerekip gerekmediği, öncesinde hiçbir çerçeveleme olmadan ilk cümlede söylenmiş. Olay kaynaklı bir release notuna rastlayan bir okuyucu, sorunu bir durum sayfasından, bir destek konusundan, veya kendi kullanıcılarından duyduğu için genellikle zaten endişelidir, ve eylem maddesinden önce bağlamla açılan bir not, tam olarak alıkoymanın en kötü okunduğu koşullarda bilgiyi alıkoyma gibi okunur. "Hiçbir işlem gerekmiyor, bu, sömürmek için kullanıcı verisi gerektirmeyen bir güvenlik açığını yamalar" ve "Hemen güncelleyin: bu sürüm bir hesabın verilerini başka birine gösterebilecek bir hatayı düzeltir" ikisi de tek bir cümledir, ve ikisi de panik içindeki bir okuyucunun başka bir şey okumadan önce ihtiyaç duyduğu tüm işi yapar.

Buna zaman kalmadığında olağan düzenleme geçişi hâlâ geçerli mi?

Sıkıştırma içgüdüsü, onu normalde üreten çoklu taslak süreci böyle olmasa bile hayatta kalır. Yeniden yazım, ayrıntılı bir ilk taslağı temel cümlesine indirmeyi tarif eder; zaman baskısı altında genellikle kesecek bir ilk taslak yoktur, ki bu disiplinin sonrasında ayrı bir geçiş olarak değil, siz yazarken kafanızda çalışması gerektiği anlamına gelir. Buna yaklaşmanın en hızlı yolu: "bilmem gereken ne" diye soran birine yüksek sesle söyleyeceğiniz cümleyi yazın, sonra durun, çünkü o cümle genellikle hem üretilmesi en hızlı hem de o durumdaki bir okuyucunun gerçekten işleyeceği tek cümledir.

Normal release notu	Acil durum release notu
Kod incelemesinden sonra, yayımlanmadan önce yazılır	Genellikle düzeltmeyle birlikte, tam inceleme öncesi yazılır
Birçok kayıt arasında taranabilirlik için optimize edilmiş	Bir kaydın stres altında izole okunması için optimize edilmiş
Detayı bağlantılı bir changelog'a erteleyebilir	En önemli tek gerçeği öne çıkarmalı
Çerçeveleme ve bağlam hoş karşılanır	Eylem maddesinden önceki çerçeveleme gecikme gibi okunur

Soruna neyin sebep olduğundan tam emin olmadan önce bir not yayımlamak hiç uygun mudur?

Evet, not sahip olmadığınız bir güveni ima etmek yerine o belirsizlik konusunda dürüstse. "Ödeme sayfasında yükselen hata oranları için bir düzeltme dağıttık; hâlâ kök nedeni doğruluyoruz ve bu notu güncelleyeceğiz" savunulabilir ve doğru şekilde zaman kazandırır; gerçekte doğrulamadığınız belirli bir nedeni belirten bir not, yanlış çıkarsa insanların size sonradan karşı gösterdiği türden bir tahmin haline gelir. Burada önemli olan disiplin teşhis hızı değildir, notun güveninin ekibin gerçek güveninden hiçbir zaman fazla olmamasıdır, çünkü acil durum notundaki yanlış bir teknik iddia, kabul edilmiş bir bilinmezden güvene daha fazla zarar verir.

Fazla emin, doğrulanmamış:
"Fixed: a race condition in the payment webhook handler
caused duplicate charges."

Zaman baskısı altında dürüst:
"Düzeltildi: bazı müşterilere tek bir sipariş için iki
kez ücret yansıtıldı. Yeni oluşumları durdurduk ve
etkilenen hesapları 24 saat içinde iade ediyoruz. Kök
neden araştırılıyor."

Bir acil durum notu soruna neyin sebep olduğunu mu, yoksa sadece düzeltildiğini mi söylemeli?

Neyin düzeltildiğini ve okuyucunun ne yapması gerektiğini söyleyin; kök nedeni tahmin edilmiş değil gerçekten bilinene kadar bir takip için saklayın. Bir olayın ortasındaki bir okuyucu tam olarak iki gerçek ister, bu çözüldü mü ve beni etkiliyor mu, ve doğru olsa bile bir kök neden açıklaması, onu kaybetmenin en kötü olası anında bu iki gerçekle dikkat için rekabet eder. İnceleme bittikten sonra ayrı yayımlanan post-mortem, kök nedenin ait olduğu yerdir; iki belgeyi zaman baskısı altında karıştırmak, yazması daha yavaş ve okuması daha yavaş bir not üretir, bir acil durumun ihtiyaç duyduğunun tam tersi.

Mobil uygulamalardaki zorunlu güncelleme sorunu burada da geçerli mi?

Aynı ilke, daha da sıkıştırılmış. Mobil uygulamalar için release notes, notun her şeyden önce nedeni ve son tarihi belirtmesi gerektiği zorunlu güncellemeleri ele alır, çünkü okuyucu zaten seçeneği olmadığı için sinirlenmiştir; acil durum web release notu genellikle okuyucu için, ona göre hareket edip etmeyeceğini seçtiği anlamda opt-in'dir, ama aynı "önce kısıtlamayı belirt" içgüdüsü uygulanır, sadece farklı bir sebeple: sinirlenme değil, aciliyet.

Öyle olmaması gerekirken bir acil durum notunun bir suç kabulü gibi okunması nasıl önlenir?

Düzeltmeyi ve etkisini tarif edin, suçu değil, ve aşırı özür dileme dürtüsüne direnin, ki bu yukarıdaki iki gerçeği isteyen bir okuyucu için dolgu gibi okunur. "Bazı export'ları etkileyen bir hata bulduk ve düzelttik", olana drama yüklemeden ne olduğunu söyler; "Değerli müşterilerimizi etkileyen bu ciddi sorun için son derece üzgünüz", okuyucunun istemediği duygusal bir anı sunmak için yararlı bilgiyi tam bir cümle geciktirir. Kısa, gerçeğe dayalı bir not soğuk değildir, gerçek baskı altında sabırsızlık olan, güvence ihtiyacı olmayan okuyucunun gerçek durumuna saygı duyar.

FAQ

Bir acil durum release notu aynı inceleme sürecinden mi geçmeli? Daha hafif bir tanesinden, hiçbirinden değil: notun kesinliği abartmadığını kontrol eden tek bir hızlı incelemeci, maliyeti birkaç dakikaya değer, çünkü incelenmemiş bir teknik iddianın yanlış olma riski tam olarak hızlı yazıldığı için daha yüksektir.

Daha fazla detaya bağlantısı olmadan bir acil durum notu yayımlamak sorun mu? Sadece kısa süreliğine. Bağlantısız bir not yayımlanan ilk şey olarak işe yarar; ikisinden biri var olur olmaz bir durum sayfasına veya takibe bir tane ekleyin, çünkü size verdiğiniz tek cümleden fazlasını isteyen bir okuyucunun gidecek bir yere ihtiyacı vardır, orası "daha fazla detay yakında" dese bile.

Bir acil durum notu hiç tamamen atlanıp düzeltmenin sessizce yayınlanmasına izin verilmeli mi? Sadece hiçbir okuyucunun fark edemeyeceği veya etkilenemeyeceği sorunlar için; bir okuyucunun sorunu yaşamış olma ihtimali varsa, not ona bittiğini söyleyen şeydir, ve sessizlik sorunun hâlâ aktif olabileceği gibi okunur.

Bir acil durum notu olay çözüldükten sonra ne kadar süre sabitlenmiş veya belirgin kalmalı? Acil kaygı penceresi kapanana kadar, tipik olarak bir veya iki gün, sonra başka herhangi bir kayıt gibi normal changelog'a katlanabilir; haftalarca sabitlenmiş kalan bir not, çözülmüş yerine çözülmemiş bir endişe gibi okunmaya başlar.

Protobuf breaking change'leri: wire'da neler hayatta kalır

Tue, 22 Sep 2026 00:00:00 GMT

Bir REST API'si bir JSON şekli değiştiğinde değişir, ve o şeklin çoğu bir tarayıcıda okuyabileceğiniz yanıtta görünürdür. Bir gRPC API'si bir .proto dosyası değiştiğinde değişir, ve Protocol Buffers'ın ikili wire formatının, alan adlarının söylediğiyle hiçbir ilgisi olmayan, bir client'ın neye tahammül edebileceğine dair kendi kuralları vardır. Diff'te eşit derecede küçük görünen iki düzenleme, bir alanı yeniden numaralandırmak ile bir tane eklemek, breaking change'in genel olarak çizdiği bir çizginin karşıt taraflarına düşer: biri mevcut her client için görünmezdir, diğeri hepsini bir anda bozar.

Protobuf breaking change'lerini güvenli olanlardan ayırmak, değişikliğin bir .proto diff'inde nasıl okunduğuna göre tahmin yürütmek değil, wire formatının kendi kurallarını okumak demektir.

Protobuf'ta alan numaralandırması neden alan adından daha çok önemlidir?

Çünkü wire formatı alanları isme göre değil, numaraya göre kodlar. Her dildeki üretilen kod bu numaraları okur ve yazar; .proto dosyanızdaki email alan adı, ağ üzerinden gönderilen ikili baytlara hiç dokunmayan, insanlar için bir kolaylıktır. Bir alanı yeniden adlandırmak, email'i email_address'e, numara aynı kaldığı sürece ikili wire'da güvenlidir, ki bu REST'e alışmış mühendisleri şaşırtır, orada yeniden adlandırılmış bir JSON key'i tam olarak bir client'ı bozan değişiklik türüdür. İstisna aynı REST durumudur: ProtoJSON ve text formatları adı serileştirir, bu yüzden yeniden adlandırma JSON transcoding'i (örneğin bir grpc-gateway), text-format dosyalarını ve field mask'leri bozar. Aynı alanı yeniden numaralandırmak, adı koruyup 1'i 7'ye değiştirmek, tam tersidir: sadece isimleri gösteren bir kod incelemesinde görünmezdir, ve o noktadan itibaren bir client'ın gönderdiği veya aldığı her mesajı bozar.

Değişiklik	Wire'da güvenli mi	Neden
Bir alanı yeniden adlandırmak, numarasını korumak	İkili evet, JSON ve text hayır	İkili kodlama numarayı kullanır; ProtoJSON ve text formatı adı kullanır
Bir alanın numarasını değiştirmek	Hayır	Mevcut her mesaj artık yanlış alan olarak okunur
Yeni numarayla yeni bir alan eklemek	Evet	Eski client'lar tanımadıkları alanları görmezden gelir
Bir alanı kaldırmak, eski numarasını başka bir şey için yeniden kullanmak	Hayır	Eski veri yanlış yeni alana kod çözülür
Bir alanın tipini uyumsuz şekilde değiştirmek (örn. `int32`'den `string`'e)	Hayır	Wire kodlaması tipe göre farklılık gösterir

Bir alanı kaldırmayı REST JSON yanıtında yapmaktan farklı kılan nedir?

Numara radyoaktif hale gelir. Protobuf'ın kendi rehberliği, kaldırılan bir alanın numarasını yeniden kullanılmasına izin vermek yerine reserved olarak işaretlemeyi önerir, çünkü gerçek hasarın olduğu yer yeniden kullanımdır: geçen ayın üretilen kodunu hâlâ çalıştıran bir client, alanın eski numarasını eski anlamı için kullanarak bir mesaj gönderir, ve artık o numaranın başka bir şey ifade etmesini bekleyen sunucu, veriyi tamamen reddetmek yerine sessizce yanlış yorumlar. REST'te eşdeğer bir tuzak yoktur, çünkü kaldırılan bir JSON key'i basitçe görünmeyi bırakır; eski bir client'ın isteğinin sessizce başka bir şey olarak yeniden yorumlanmasının bir yolu yoktur. Bir mesajın en üstünde reserved 4, 9, 12; olan bir .proto dosyası kalıcı bir yaradır, ve amaç budur: numaranın, tarihini bilmeyen biri tarafından yeni bir alana verilmesini engeller.

message Invoice {
  reserved 4; // eskiden `legacy_customer_id`, 2026-06-01'de silindi
  reserved "legacy_customer_id"; // adı da, JSON/text için
  string customer_id = 5;
  string status = 6;
}

Bir alan eklemek hiç bir changelog kaydı gerektirir mi?

Genellikle breaking change kaydı değil, ama sıklıkla normal bir kayıt gerektirir, çünkü "wire'da güvenli" ile "önemseyen bir okuyucu için görünmez" iki farklı iddiadır. Bir yanıt mesajına alan eklemek yapısal olarak hiçbir şeye mal olmaz, eski client'lar mesajı kod çözer ve yeni alanı otomatik olarak görmezden gelir. Ama o servise karşı yeni bir entegrasyon kuran biri, birisi ona söylemedikçe alanın var olduğunu bilmenin bir yolunu bulamaz, çünkü başarılı bir build veya geçen bir testte yeni bir opsiyonel alanı görünür kılan hiçbir şey yoktur. API changelog genel olarak eklemeli bir kaydın okuyuculara ne borçlu olduğunu ele alır; yine de bir tane yazmanın gRPC'ye özgü nedeni, bir hata ayıklayıcıda REST yanıtına göz atarak yeni bir key'in ortaya çıktığını fark etmenin bir eşdeğerinin olmamasıdır.

Bu, GraphQL çağıranların uğraştığı şeyden nasıl farklıdır?

Eklemeler için kurallar aynıdır, ama maruziyet farklıdır. GraphQL şema deprecation'ı, bir client'ın yalnızca açıkça istediği alanları aldığı bir modeli ele alır, ki bu eklemeli değişiklikleri esasen risksiz ve kaldırmaları tek gerçek tehlike yapar. gRPC client'ları ise sunucunun gönderdiği her şeyi alır ve hepsini kendi derlenmiş şema kopyasına karşı kod çözer; bir client'ın maruziyeti istediğiyle sınırlı değildir, sadece üretilen kodunun ne okuyabildiğiyle sınırlıdır. Bu fark changelog yazarken önemlidir: bir GraphQL kaydı, client'ların istemedikleri alanlardan korunduğunu makul olarak varsayabilir, ve bir gRPC kaydı bunu hiç varsayamaz.

Bir gRPC servisini versiyonlamak REST'in `/v1/`, `/v2/`'si gibi mi çalışır?

Niyet aynı olsa bile mekanizma farklıdır. Bir REST API'sinde v1 ve v2 nedir, versiyonlamayı farklı sözleşmelere hizmet eden paralel URL yolları olarak ele alır; gRPC servisleri tipik olarak .proto dosyasının kendisindeki paket adı üzerinden versiyonlanır, payments.v1.InvoiceService, bir client'ın istediği bir URL segmenti yerine çevirdiği tam nitelikli servis adını değiştirerek payments.v2.InvoiceService olur. Her iki yaklaşım da aynı sorunu çözer, yeni biri varken eski bir sözleşmenin çalışmaya devam etmesine izin vermek, ama REST geçmişinden gelen bir ekip genellikle bir versiyon numarasını yanlış yerde arar ve paket bildiriminin o işi yaptığını kaçırır.

Bir gRPC changelog kaydı gerçekte neyi adlandırmalı?

Mesajı, alan numarasını, ve eylemde bulunup bulunmayacağına karar veren bir okuyucu için önem sırasına göre, ekleme mi yoksa migrasyon gerektiren bir kaldırma mı olduğunu. "Order'a shipping_address (alan 8) eklendi", bir entegratöre üretilen kodu güncellemek ve kullanmaya başlamak için gereken her şeyi söyler. "Invoice'ta alan 4 rezerve edildi, legacy_customer_id kayboldu", ona kod tabanlarındaki herhangi bir şeyin hâlâ o alanı okuyup okumadığını kontrol etmesini söyler, ki bu REST tarzı bir "yanıttan bir alan kaldırıldı" notunun aynı aciliyetle iletmediği bir şeydir, çünkü REST kaldırmaları sadece daha az veri döndürürken Protobuf alan yeniden kullanımı onu aktif olarak bozar.

FAQ

Bir alanın tipi wire formatını bozmadan hiç değiştirilebilir mi? Sadece Protobuf'ın belgelediği belirli uyumlu gruplar içinde, bazı durumlarda int32'yi int64'e genişletmek gibi. Protobuf'ın kendi uyumluluk tablosuna karşı kontrol etmediğiniz sürece herhangi bir tip değişikliğini bozucu olarak ele alın; bir dilin tip sistemiyle benzetme yaparak uyumluluk varsaymak, bunun yanlış gitme şeklidir.

Protobuf'ta bir alanı deprecate etmek GraphQL'in @deprecated direktifi gibi mi çalışır? Benzer şekilde: Protobuf, araçların gösterebileceği bir [deprecated = true] alan seçeneğini destekler. İkisi de zorunlu kılınmaz: bir GraphQL sunucusu deprecate edilmiş bir alan için gelen sorguyu yine yanıtlar, ve bir protobuf client'ı onu yine kodlar. İkisi de tavsiye niteliğindedir ve aynı changelog desteğine ihtiyaç duyar.

Her client'ı kontrol ediyorsanız yeniden numaralandırma hiç güvenli midir? Tamamen kapalı bir sistemde, ilke olarak, ama alan numaralarının var olma nedeni olan tüm güvenlik özelliğini ortadan kaldırır, ve "her client'ı kontrol ediyoruz" bir build önbelleğe alındığı, bir deploy geciktirildiği, veya kimsenin hatırlamadığı bir client eklendiği anda doğru olmaktan çıkan bir iddiadır. Numarayı yeniden kullanmak yerine, dahili olarak bile, rezerve edin.

gRPC servisleri genel bir REST API'si gibi bir changelog sayfasına ihtiyaç duyar mı? Sadece harici ekipler .proto diff'lerini doğrudan okumadan onları tüketiyorsa, dahili API changelog'ları'nın genel olarak uyguladığı aynı "karşı tarafta kim var" testi. Sadece aynı ekibin diğer servisleri tarafından tüketilen bir gRPC servisi, genellikle commit geçmişi lehine resmi bir changelog'u atlayabilir, çünkü onu okuyan herkesin şeması zaten açıktır.

Changelog dosya formatları: JSON, YAML veya sadece Markdown

Thu, 17 Sep 2026 00:00:00 GMT

Çoğu ekip bir changelog'a Markdown dosyası olarak başlar çünkü bu en az direnç gösteren yoldur: bir pull request diff'inde okunabilir, GitHub'da hiçbir şey render etmeden okunabilir, ve bir README yazmış herkese tanıdıktır. Bu seçim, dosyayı bir insan dışında bir şeyin okuması gerekene, bir sayfa, bir widget, bir e-posta özeti, kadar iyi çalışır, ve o zaman format ücretsiz olmayı bırakır. Changelog otomasyonu yapısal gereksinimi genel olarak ele alır, bir tür, bir tarih, bir gövde ve bir bağlantı; bu yazı hangi dosya formatının bu yapıyı gerçekten sağladığını ve her birine oraya varmanın neye mal olduğunu ele alır.

Basit bir Markdown changelog'unda yanlış olan ne?

Bir şey onu tekrar alanlara ayrıştırması gerekene kadar hiçbir şey. Bir başlık, bir tarih ve altında bir madde işaretli liste, bir insan için okumak önemsizdir ve gerçekten güvenilir bir şekilde ayrıştırmak zordur, çünkü Markdown'un bir şeması yoktur: tarih başlıkta olabilir, ilk satırda kalın yazıyla olabilir, veya eski bir kayıtta tamamen eksik olabilir, ve bu varyasyonların her biri bir insanın doğru okuduğu ve bir ayrıştırıcının okumadığı geçerli Markdown'dır. Bir Markdown changelog'u otomatikleştiren ekipler genellikle bir kaydın biçimlendirmesi hafifçe kaydığında bile bozulan, regex tabanlı özel bir ayrıştırıcı yazmakla sonuçlanır, ki bu sık yaşanır, çünkü yazarken hiçbir şey tutarlılığı zorlamaz.

Yapılandırılmış bir format gerçekte size ne kazandırır?

Her kaydın aynı şekle sahip olduğuna dair, kayıt okunduğunda tahmin edilen değil, kayıt yazıldığında kontrol edilen bir garanti. Tanımlı bir şemaya sahip bir JSON veya YAML dosyası, tür, tarih, versiyon, hedef kitle, gövde, bağlantı, tıpkı katı bir API yanıtının yapacağı gibi gerekli bir alan eksikse gürültülü bir şekilde başarısız olur; bir Markdown dosyası orada olanı, doğru olsun olmasın, sadece render eder. Bu fark, bir betiğin bir akışı sıralamak için her kaydın tarihine ihtiyaç duyduğu ve kayıtların yarısının bunu farklı bir yerde tuttuğu güne kadar görünmezdir.

# CHANGELOG.yml
- date: 2026-09-05
  type: breaking
  version: v2
  audience: api
  body: "POST /invoices now rejects a currency mismatch instead of silently converting."
  link: /blog/api-changelog/

Bu, insan tarafından okunabilir dosyanın kaybolması gerektiği anlamına mı gelir?

Hayır, ve bir YAML veya JSON dosyasının aynı zamanda bir insanın bir pull request'te okuduğu şey olmasını sağlamaya çalışmak genellikle ters yönde bir hatadır: iç içe geçmiş JSON'un diff'ini incelemek, bir düz yazı cümlesini incelemekten daha kötüdür, ve bir ifade hatasını yakalamak için bir veri yapısını zihinsel olarak ayrıştırması gereken bir incelemeci, sonunda ifade hatalarını yakalamayı bırakacak bir incelemecidir. İki format bir arada var olabilir: yapılandırılmış veri, bir otomasyon pipeline'ının okuduğu doğruluk kaynağıdır, ve üretilmiş bir Markdown veya HTML render'ı, bir insanın gerçekten incelediği ve okuduğu şeydir, elle yanında tutulmak yerine yapılandırılmış dosyadan üretilir.

Format	Olduğu gibi insan tarafından okunabilir	Özel kod olmadan makine tarafından ayrıştırılabilir	Yaygın başarısızlık modu
Markdown	Evet	Hayır	Tutarsız kayıt şekli naif ayrıştırıcıları bozar
JSON	Zayıf	Evet	Ayrıntılı; elle geçersiz JSON'a düzenlemek kolay
YAML	Orta	Evet	Boşluğa duyarlı; kötü bir girinti gürültülü değil sessiz bir ayrıştırma hatasıdır

Hangi yapılandırılmış format elle düzenlemek için gerçekte daha kolay, JSON mu YAML mı?

YAML, bir üretici yerine elle kayıt yazan herkes için, çünkü JSON'un her string ve iç içe nesne için gerektirdiği tırnak işaretleme ve parantez eşleştirmeyi ortadan kaldırır. Ödünleşim, YAML'in boşluk duyarlılığının, JSON'un parantez uyuşmazlıklarının genellikle yapmadığı bir şekilde sessizce başarısız olmasıdır: bir JSON ayrıştırıcısı hatalı biçimlendirilmiş girdiyi doğrudan reddeder, YAML ayrıştırıcısı ise kötü girintilenmiş bir dosyayı kabul edip onu yanlış yapıya basitçe ayrıştırabilir, ki bu daha kötü bir başarısızlıktır çünkü hiçbir şey size bunun olduğunu söylemez. Kayıtlar sadece her zaman bir betik tarafından yazılıyorsa, bu ödünleşim büyük ölçüde ortadan kalkar ve JSON'un daha katı ayrıştırması daha güvenli varsayılan seçim haline gelir.

Bir changelog sayfasının, onu besleyen dosyadan ayrı kendi yapılandırılmış formatına ihtiyacı var mı?

Ayrı birine değil, farklı render edilmiş aynısına. Bir changelog sayfası, sayfanın kendisini bir JSON akışı ve schema.org işaretlemesi aracılığıyla nasıl makine tarafından okunabilir hale getireceğinizi ele alır; o akış üretilmiş bir çıktıdır, altta yatan dosyayla senkronize tutulacak ikinci bir doğruluk kaynağı değildir. Yapılandırılmış veriyi iki yerde, bir kaynak dosyada ve bir sayfanın akışında, elle tutmak, ikisinin nasıl ayrıştığıdır, bu yüzden burada verilen dosya formatı kararı, sonrasındaki her şeyin, sayfa, widget, e-posta, üretildiği tek şey olmalı, asla elle kopyalanmamalı.

Mevcut bir Markdown changelog'unu yapılandırılmış bir formata dönüştürmek geçiş maliyetine değer mi?

Genellikle sadece otomasyon gerçek hedef olduğunda, öncesinde değil. Bir GitHub README'sine Markdown dosyası yayınlayan tek kişilik bir proje gerçek bir otomasyon ihtiyacına sahip değildir, ve onu YAML'e dönüştürmek törenden başka bir şey satın almaz. Dönüşüm, birden fazla aşağı akış tüketicisinin, bir sayfa, bir özet e-postası, herkese açık bir akış, aynı veriyi okuması gerektiği anda kendini amorti eder, çünkü bu tam olarak bir Markdown ayrıştırıcısının tutarsızlıklarının sadece bakımı sıkıcı olmak yerine görünür şekilde yanlış çıktı üretmeye başladığı noktadır.

FAQ

Bir Markdown changelog'u formatı tamamen değiştirmeden ayrıştırılabilir hale getirilebilir mi? Kısmen, frontmatter ile: her kaydın başında küçük bir YAML bloğu (tarih, tür, versiyon), düz yazı için bir Markdown gövdesinin yanında. Bu, tüm kaydı JSON veya YAML'e zorlamadan bir ayrıştırıcının ihtiyaç duyduğu yapılandırılmış alanları elde eder, ve tam bir geçişe henüz hazır olmayan bir ekip için makul bir orta yoldur.

Dosya formatı SEO için veya bir changelog sayfasının nasıl sıralandığı için önemli mi? Doğrudan değil. Arama motorları render edilmiş sayfayı okur, kaynak dosyayı değil, bu yüzden dosya formatı onlar için görünmezdir; sayfanın kendisi için önemli olan, kendi hakkıyla makine tarafından okunabilir olup olmadığıdır, ki bu onu neyin ürettiğinden ayrı bir konudur.

Her changelog kaydı aynı dosyadan mı geçmeli, yoksa türler dosyalar arasında bölünebilir mi? Tek bir dosya, kayıt hacmi onu diff'lemek veya incelemek için hantal hale getirene kadar daha basittir; yıla veya kategoriye göre bölmek, tek bir dosyanın diff'leri mantıklı bir şekilde incelenemeyecek kadar büyüdüğünde makul bir güvenlik supabıdır, ama aşağı akıştaki herhangi bir şeyin "tüm kayıtları" tek bir liste olarak okuyabilmesinden önce bir birleştirme adımı ekler.

RSS için bir standart olduğu gibi standart bir changelog dosya formatı var mı? Geniş çapta benimsenmiş bir tane yok. Keep a Changelog bir Markdown kuralı önerir, ve birkaç aracın kendi formatı vardır; bir changeset paketi ve sürüm artışını adlandıran YAML frontmatter'lı bir Markdown dosyasıdır, yani yukarıda anlatılan frontmatter kalıbının ta kendisi. Bunların hiçbiri RSS okuyucularının RSS'i evrensel olarak anladığı gibi diğer araçların kutudan çıktığı gibi okuduğu bir format değildir.

Yinelenen özellik talepleri: sesi kaybetmeden birleştirmek

Thu, 17 Sep 2026 00:00:00 GMT

Üç müşteri aynı yeteneği üç farklı haftada, üç farklı şekilde ifade ederek talep eder, ve yinelenenleri yakalamak için kurulmuş bir triyaj süreci işini yapar: onları gruplar, üç oylu tek bir talep olarak sayar, ve backlog temiz kalır. Kolay olan kısım budur. Hangi etiketler işe yarar, yinelenenler için mekanik çözüm olarak ifadeye göre triyaj etmeden önce temel yeteneğe göre gruplamayı ele alır; ele almadığı şey, üç talep tek bir satır kalemine dönüştüğünde kelimelerin kendisine ne olduğudur, ve bu kayıp genellikle çözdüğü yinelenen sayma sorunundan daha büyüktür.

Yinelenenler birleştirildiğinde gerçekte ne kaybedilir?

Her talep edenin kullandığı, sıkça çöktüğü oy sayısından daha bilgilendirici olan spesifik ifade. Bir müşteri "filtrelenmiş sonuçları dışa aktarmanın bir yolu" isteyebilir, bir diğeri "kaydedilmiş filtrelerime saygı gösteren CSV dışa aktarma", ve üçüncüsü "gizli sütunları içermeyen dışa aktarma". Üçü de aynı temel talep, doğru şekilde gruplanmış, ama her ifade o kişi için neyin önemli olduğuna dair hafifçe farklı bir vurgu taşır, ve sadece ilk gönderimin ifadesini koruyan bir birleştirme diğer ikisini tamamen atar. Sayım hayatta kalır; birinin özelliğin doğru versiyonunu inşa etmesine yardımcı olacak doku hayatta kalmaz.

Oy sayısı zaten talebin var olduğunu söylüyorsa doku neden önemli?

Çünkü talep ve tasarım farklı sorulardır, ve sadece spesifik ifade ikincisini cevaplar. "Dışa aktarma" üzerinde on oy, bir ekibe özelliği inşa etmeye değdiğini söyler; "dışa aktarma"nın CSV, PDF, planlanmış bir e-posta, yoksa bir API endpoint'i mi anlamına geldiği hakkında hiçbir şey söylemez, ve ilk gönderimin ifadesi lehine on orijinal gönderimden dokuzunu atan bir birleştirme, diğer dokuzu ince bir şekilde farklı bir şey istese bile spesifikasyonu sessizce ilk talep edenin tesadüfen istediği şeye daraltabilir. Bir özellik talebinin gerçekte neyi kaydetmesi gerektiği, bu aynı boşluğu alım tarafından ele alır; yinelenenleri birleştirmek, bunun alımdan sonra yeniden ortaya çıktığı yerdir, tam olarak bir ekibin gerçekte ne istendiğinin aralığına en çok ihtiyaç duyduğu noktada.

İfadeyi atmak yerine koruyan bir birleştirme süreci nasıl görünür?

Değiştirmek yerine eklemek. Kanonik öğe backlog görünümü için tek bir başlık korur, ama birleştirilen her gönderimin orijinal ifadesi ona bağlı kalır, alıntılar listesi olarak veya bağlantılı kaynak biletler olarak, böylece öğeyi daha sonra inceleyen herkes bir ekip üyesinin özetinin yerine insanların gerçekten istediği şeyin gerçek aralığını görebilir. Bunu inşa etmek neredeyse hiçbir şeye mal olmaz, yeni bir sistem yerine bilette bir alan, ve bu bilgiyi sıkıştıran bir birleştirme ile sadece görüntüsünü sıkıştıran bir birleştirme arasındaki farktır.

Özellik: Filtrelenmiş CSV dışa aktarma
Oylar: 12
Birleştirilen talepler:
  - "filtrelenmiş sonuçları dışa aktarmanın bir yolu" (acct_4421)
  - "kaydedilmiş filtrelerime saygı gösteren CSV dışa aktarma" (acct_8832)
  - "gizli sütunları içermeyen dışa aktarma" (acct_1097)
  ...

Her yinelenen birleştirilmeyi hak eder mi, yoksa yanlış eşleşmeler var mı?

Bazıları yanlış eşleşmelerdir, ve "benzer geliyor"u "aynı talep"miş gibi ele almak kendi başına bir başarısızlık modudur. "Verilerimi dışa aktarmama izin ver" ve "sadece filtrelenmiş görünümü dışa aktarmama izin ver", aslında aynı genel yeteneğin iki farklı kapsamını tanımlarken "dışa aktarma" üzerinde bir anahtar kelime eşleşmesiyle gruplanabilir; onları birleştirmek ya yanlış şey için oy sayısını şişirir ya da, daha kötüsü, tesadüfen önce geldiği için daha dar versiyonu gönderir. Gruplama üzerinde bir insan geçişi, hızlı bile olsa, bu birikmeden önce bunu yakalar; otomatik bir benzerlik eşleştirmesi tek başına kelime dağarcığında aşırı birleştirir ve niyette yetersiz birleştirir.

Yinelenen kontrolü gerçekte ne zaman çalışmalı, alımda mı yoksa daha sonra mı?

İkisi de, farklı nedenlerle. Alımda kontrol etmek, açık olanı, zaten açık olan bir şeyi tekrar eden yeni bir talebi, kendi izlenmeyen satırına dönüşmeden önce yakalar; gönderim anında açık taleplere karşı bir benzerlik araması bunların çoğunu insan müdahalesi olmadan halleder. Daha yavaş bir ritimde yapılan sonraki bir geçiş, alımın kaçırdığı durumu yakalar: o sırada bir anahtar kelime veya embedding eşleşmesinden kaçacak kadar farklı bir dil kullanan, ama bir ekip düzinelerce varyasyon gördükten sonra aynı temel yeteneği tanımladığı ortaya çıkan iki talep. İkinci geçişi atlamak, yakın yinelenenleri süresiz olarak ayrı başlıklar altında dağınık bırakır, her biri kendi başına asla inşa edilecek sayıya ulaşmayan küçük bir oy sayısıyla.

Talep eden, gönderiminin mevcut bir öğeye birleştirildiğini bilmeli mi?

Evet, ve bu müşteri geri bildirim döngüsünü kapatmak ile aynı disiplindir, sadece alışılmıştan bir adım daha erken uygulanır: bir şey gönderip hiç haber almayan bir talep eden, sonunda gönderilen on bir başka oyla bir öğeye doğru şekilde birleştirilmiş olsa bile, talebinin hiçbir yere gitmediği sonucuna varır. Kısa bir onay, "bunu başkalarının da yaptığı mevcut bir talep ile birleştirdik", bir mesaja mal olur ve bir müşterinin onu gerçekten takip edip etmediğine dair hiçbir görünürlüğü olmadığı için aynı talebi birkaç ayda bir yeniden göndermesini önler.

Birleştirme, özellik gönderildiğinde kime kredi verildiğini değiştirir mi?

İlk gönderen kişiye değil, herkese kredi vermelidir. Geri bildirim döngüsünü kapatmak, talep edenlere talepleri gönderildiğinde bildirmeyi ele alır; birleştirilmiş bir öğe için bu, ifadesi kanonik başlık haline gelen hesap değil, birleştirmeye bağlı her hesap anlamına gelir, çünkü her talep edenin bakış açısından o bunu istedi ve gönderildi, bir triyaj sürecinin tesadüfen hangi ifadeyi koruduğuna bakılmaksızın. Changeloop'ta bu, pull request'in bağlantılı her issue'yu adlandırması demektir (Fixes #142, fixes #187); adlandırmadığı bir issue yorum almaz.

FAQ

Birleştirilen her talep için bir alıntı mı yoksa tam bir bilet bağlantısı mı, ne kadar ifade korunmaya değer? Kısa bir alıntı genellikle yaygın durum için yeterlidir, çünkü amacı bir incelemecinin ifade aralığını bir bakışta görmesini sağlamaktır; orijinalin bir ekran görüntüsü veya tek satırlık bir alıntının düzleştireceği ayrıntılı bir iş akışı açıklaması gibi önemli ek bağlamı olduğunda tam bilet bağlantısını da koruyun.

Her yinelenenin ifadesini korumak backlog'u taramayı zorlaştırır mı? Varsayılan olarak daraltılmışsa hayır. Kanonik başlık, tarayan bir incelemecinin gördüğü şeydir; birleştirilmiş ifade bir tık veya bir genişletme uzaklıktadır, daha derin araştırma yapan kişi için mevcuttur ama sadece oy sayan biri için görünümü karmaşıklaştırmaz.

İki talep aynı görünüyor ama inşa edildiğinde farklı şeyler istediği ortaya çıkarsa ne olur? Bu netleştiği anda onları tekrar ayırın, ve orijinal birleştirmeyi tekrarlamaktan kaçınılması gereken bir hata olarak değil, o zaman mevcut bilgiyle yapılmış makul bir karar olarak ele alın. Hiçbir şeyi asla ayırmayan bir gruplama sistemi, sonunda kalıcı olarak pişmiş birkaç yanlış birleştirmeye sahip olacaktır.

Birleştirilen bir talebin altında yatan ifadenin insan incelemesini alması gereken bir oy eşiği var mı? Sabit bir sayı yok, ama bir inşa kararına yaklaşan herhangi bir talep oy sayısından bağımsız olarak bunu hak eder, çünkü bu, "dışa aktarma" ile "kaydedilmiş filtrelerle CSV olarak dışa aktarma" arasındaki farkın bir nüans olmaktan çıkıp spesifikasyon olmaya başladığı noktadır.

Versiyon numarası olmadan GraphQL deprecation

Thu, 17 Sep 2026 00:00:00 GMT

Bir REST API'si /v1/'in yanında /v2/'yi de yayınlayabilir ve çağıranların kendi hızlarında geçiş yapmasına izin verebilir. GraphQL'in bir endpoint'te tek bir şeması vardır, ve her client, geçen yılın build'indeki mobil uygulama ve bu sabah dağıtılan dahili dashboard, aynı grafiği sorgular. Fork'lanacak bir URL yoktur. Bir alanı deprecate etmek, herkesin zaten bağımlı olduğu bir şemada, onu yerinde deprecated olarak işaretlemek anlamına gelir, bu da disiplini REST'ten farklı kılar, temelde yatan sorun, çağıranlara bir şeyin kaybolacağını söylemek, API deprecation'ın genel olarak ele aldığı sorunla aynı olsa bile.

Artırılacak bir versiyon yoksa GraphQL bir alanı deprecated olarak nasıl işaretler?

Doğrudan alana uygulanan @deprecated direktifiyle:

type Product {
  price: Float @deprecated(reason: "Use priceV2 for multi-currency support.")
  priceV2: Money
}

Alan sorgulanabilir kalır. Kaybolmaz, 404 vermez, davranışını değiştirmez; sadece çoğu GraphQL aracının, GraphiQL, Apollo Studio, şema linter'ları, şemaya göz atan veya ona karşı bir sorgu yazan herkese göstereceği, makine tarafından okunabilir bir not taşır. Mekanizma budur, hepsi bu kadar. Ayrı bir deprecation endpoint'i, header, ya da spec'in gerektirdiği bir eşlik eden belge yoktur, ki bu hem cazibesi hem de tuzağıdır: direktifi eklemek kolaydır ve görmezden gelmek de kolaydır, çünkü hiçbir şey bir client'ı ona bakmaya zorlamaz.

Deprecation nedenini gerçekten gören var mı?

Sadece şemayı doğrudan, introspection veya şemayı bilen bir editör aracılığıyla kullananlar, ve bu bir API changelog'unun alışılmış okuyucularından daha küçük bir kitledir. Altı ay önce bir sorguya karşı inşa edilmiş bir mobil uygulama o sorguyu zaten binary'sine pişirmiştir; deprecated olsun olmasın, biri uygulamayı yeni alanla yeniden inşa edip bir güncelleme yayınlayana kadar price'ı istemeye ve cevap almaya devam edecektir. Direktif, yeni kod yazan bir geliştiriciye eski alanı kullanmamasını söyler. Zaten yayınlanmış ve çalışan client için hiçbir şey yapmaz.

Mekanizma	Kime ulaşır
`@deprecated` direktifi	Şemaya göz atan veya yeni sorgular yazan geliştiriciler
Şema linter CI hataları	Bir tane çalıştırıyorsa client kod tabanına sahip ekip
Bir changelog kaydı	Linter'ı olmayan bir client ekibi dahil, onu okuyan herkes
Hiçbir şey (alan çalışmaya devam eder)	Eski alanı kullanan zaten inşa edilmiş bir client

Deprecated bir alan yine de bir changelog kaydı almalı mı?

Evet, ve tek başına direktiften daha fazla iş yapar, çünkü bir changelog direktifin ulaşamadığı insanlara ulaşır: şemasına göz atmadan grafiği tüketen bir ortak ekip, aylar önceki önbelleğe alınmış bir şema kopyasına karşı inşa edilmiş bir client, bunu sadece düz yazı okuyarak fark edecek herkes. API changelog'u bir kaydın çağırana genel olarak neyi borçlu olduğunu ele alır; bir GraphQL kaydı, REST'in nadiren açıkça belirtmesi gereken bir şeyi borçludur, çünkü REST çağıranları bunu versiyon numarasından çıkarır: eski alan bugün hâlâ çalışıyor mu, bir uyarıyla hâlâ çalışıyor mu, yoksa gerçekten veri döndürmeyi bırakmış mı. Direktif tek başına, şemayı hiç açmamış bir okuyucu için bunların hiçbirine cevap vermez.

Bir alanı şemadan kaldırmak gerçekte ne zaman güvenlidir?

Sadece sorgu günlükleri artık kimsenin onu istemediğini gösterdiğinde, ki bu bir kullanım sorusudur, takvim sorusu değil. Bir alan bir yıl boyunca @deprecated taşıyabilir ve hiç yeniden inşa edilmemiş bir client için hâlâ taşıyıcı olabilir; bir REST Sunset header'ının sık yaptığı gibi onu sabit bir takvimde kaldırmak, o client'ı üzerinde hareket edebileceği hiçbir uyarı olmadan bozar, çünkü GraphQL ona hiç okumadığı direktif dışında üzerinde hareket edebileceği hiçbir şey vermez. Bir kaldırma tarihine bağlanmadan önce alan düzeyinde kullanımı loglayın, ve sıfır olmayan herhangi bir sorgu sayısını geri sayım olarak değil, bir bekletme olarak ele alın.

Bir alan eklemek REST API'sindeki ile aynı riski taşır mı?

Yeni bir alan için daha az, çünkü bir GraphQL client'ı sadece açıkça istediği alanları alır. price'ın yanına priceV2 eklemek, REST JSON yanıtına bir alan eklemenin katı bir deserializer'ı bozabileceği şekilde mevcut bir sorguyu bozamaz, çünkü hiçbir şey client'ı yeni alanı istemeye zorlamaz. Mevcut bir enum'a yeni bir değer eklemek aynı nefeste belirtmeye değer istisnadır: güçlü tipli dillerin teşvik ettiği gibi her enum değerinde exhaustive switch yapan bir client, herhangi bir sorgu onu istemiş olsun ya da olmasın, yeni bir değer geldiği anda bozulur. Bu güvenlik sadece client'ın kendi isteğiyle dahil olduğu alanlar ve union üyeleri için geçerlidir; client'ın kodunun elle numaralandırdığı kapalı bir küme için geçerli değildir.

Bir GraphQL changelog kaydı bir REST kaydının ihtiyaç duymadığı neye ihtiyaç duyar?

Sadece alan adına değil, sorgu şekline, çünkü "price alanı deprecated" bir çağıranın gerçekten ihtiyaç duyduğu parçayı eksik bırakır: hangi tipler ve hangi sorgular ona dokunuyor. Yararlı bir kayıt tipi, alanı, yerine geçen alanı ve, üretebiliyorsanız, üretimde hâlâ eski şekli isteyen gerçek sorguları adlandırır. Bu son parça, deprecation bildirimini gerçek kullanıma bağlamak, REST çağıranlarının bir URL'deki sunucu günlüklerinden bedavaya aldığı ve GraphQL çağıranlarının almadığı bir şeydir, çünkü her sorgu ne isterse istesin aynı endpoint'e çarpar.

`@deprecated` direktifini alan dışında başka bir şey taşıyabilir mi?

Enum değerleri, aynı direktifi alanınkinin yerine değerin kendi tanımında kullanarak:

enum ShippingMethod {
  STANDARD
  EXPRESS
  OVERNIGHT @deprecated(reason: "Use EXPRESS with priority: true instead.")
}

Spec, @deprecated'i tam olarak iki konum için tanımlar, bir alan tanımı veya bir enum değeri, ve stabil sürüm itibarıyla başka hiçbir şey için; argüman ve input-field düzeyinde deprecation sadece daha sonraki taslak dilde var, bugün çoğu sunucunun uyguladığı şeyde değil. Bu şekilde işaretlenmiş bir enum değeri, bir sunucunun hâlâ döndürebileceği veya kabul edebileceği geçerli bir değer olarak kalır, deprecated bir alanın yaptığı aynı breaking-olmayan vaat, ki bu da onu değeri gerçekten kaldırmadan önce göndermeyi güvenli kılan şeydir.

FAQ

GraphQL, tüm bir endpoint için Sunset header'ı gibi bir şeyi destekler mi? Hayır, çünkü genellikle sadece bir endpoint vardır. Deprecation zamanlaması alan düzeyinde, @deprecated direktifinin neden metninde ve bir ekibin onun yanında yayınladığı changelog veya geçiş kılavuzunda yaşar, bir client'ın programatik olarak okuyabileceği bir yanıt header'ında değil.

Deprecated bir alan kaldırılıp sonra farklı bir tiple yeniden eklenebilir mi? Sadece yeni bir alan adı olarak. Aynı alan adını değişmiş bir tiple yeniden tanıtmak, tam olarak deprecation döngüsünün önlemek için var olduğu breaking change'dir; yerine geçene priceV2'nin yaptığı gibi kendi adını verin, ve isim yeniden kullanılabilir hale gelmeden önce eskisinin tamamen sönmesine izin verin.

@deprecated neden metni changelog kaydına bağlantı vermeli mi? Şema araçları destekliyorsa, evet. Neden alanı düz bir string kabul eder, ve o string içindeki bir URL, introspection çıktısına bakan bir geliştiriciden bir changelog kaydının verebileceği daha kapsamlı açıklamaya giden en kısa yoldur.

Bir GraphQL şema değişikliği hiç REST'in olmadığı bir şekilde geriye dönük uyumlu mudur? Eklemeli alan değişiklikleri, evet, yukarıdaki nedenden dolayı: client'lar sadece istedikleri şeyi alır. Yeni enum değerleri istisnadır, çünkü kapalı bir kümeyi numaralandıran bir client, beklemediği bir değerde bozulabilir. Kaldırmalar ve tip değişiklikleri REST karşılıkları kadar tam olarak breaking'dir.

API geçiş kılavuzu nasıl yazılır

Mon, 07 Sep 2026 00:00:00 GMT

API geçiş kılavuzu, uyumsuz bir değişikliği kesintiye değil kontrol listesine dönüştüren belgedir: ne değişti, bu konuda ne yapılmalı, ve ne zamana kadar. Bir changelog girişi uyumsuz bir değişikliği iki cümlede adlandırabilir; geçiş kılavuzu, o iki cümle "bu seni etkiler" dediğinde ve çağıranın tam olarak neyi değiştirmesi gerektiğini bilmesi gerektiğinde gerçekten açtığı şeydir. Girişi kılavuz olmadan yayınlamak, çağıranın uyumsuz bir değişikliği tam da bunu önlemek için yazılmış belge yerine bir destek biletinden öğrenmesinin yoludur.

API geçiş kılavuzu nedir?

Çağıranı bir API'nin eski biçiminden yenisine götüren, adım adım bir belge; değiştirilecek kodu olan biri için yazılır, API'yi hiç kullanıp kullanmayacağına karar veren biri için değil. Bu ayrım önemlidir: bir geçiş kılavuzu mevcut bir entegrasyon ve mevcut üretim trafiği varsayar, bu yüzden geri alma, kısmi geçiş, ve geçişin başarılı olup olmadığının nasıl anlaşılacağını kapsamak zorundadır, bunların hiçbiri ilk entegrasyon kılavuzuna gerek değildir.

Belge	Varsayar	Yanıtladığı
Geçiş kılavuzu	Mevcut bir entegrasyon	Eski biçimden yeniye nasıl geçerim?
Changelog girişi	Hiçbir şey, sadece okuyucunun kontrol etmesi	Ne değişti, ve ne zaman?
API referansı	Hiçbir şey, veya ilk entegrasyon	Bu endpoint ne yapar?
Deprecation bildirimi	Eskiyi kullanan bir entegrasyon	Bu ne zaman çalışmayı bırakır?

Bir geçiş kılavuzu genellikle son ikisi arasında yer alır: bir deprecation bildirimi bir saati başlatır, ve geçiş kılavuzu çağıranın o saat dolmadan önce izlediği şeydir.

Bir değişiklik ne zaman sadece changelog girişi değil, geçiş kılavuzu gerektirir?

Eski ve yeni davranış arasında birden fazla adım olduğunda, veya değişiklik yeterince çağrı noktasını etkilediğinde, çağıran bir açıklamadan çok işlenmiş bir örnekten fayda görür. Uyumsuz bir değişiklik nedir, ve nasıl gönderilir bir değişikliğin uyumsuz olup olmadığına dair testi ele alır; yanıt evetse, ikinci soru düzeltmenin tek satırlık bir düzenleme mi yoksa gerçek bir geçiş mi olduğudur. Yeniden adlandırılmış bir alanı çağıran sadece changelog girişinden halledebilir. Kimlik doğrulama, sayfalama veya hata işlemedeki bir değişiklik neredeyse her zaman bir kılavuzu hak eder, çünkü doğru yedek kod tek cümlelik bir açıklamadan belli değildir.

Bir geçiş kılavuzu neyi içermelidir?

Beş şey, ve herhangi birini atlamak bir kılavuzu çağıranın bir kez okuyup sonra deneme yanılmaya döndüğü bir sayfaya çevirir. Eski kod, bir projede gerçekte görüneceği gibi gösterilmiş. Yeni kod, aynı şekilde gösterilmiş, farkın soyut bir tanımı olarak değil. Hiçbir şey değişmezse ne bozulur, açıkça söylenmiş, çünkü "hiçbir şey" geçerli ve yaygın bir yanıttır ve çağıranın yine de bunu açıkça duyması gerekir. Geçişin işe yarayıp yaramadığını doğrulamanın bir yolu, bir yanıt alanı veya kontrol edilecek bir durum kodu gibi. Ve bir zaman çizelgesi: eski davranış ne zaman çalışmayı bırakır, ve arada her iki biçim de kullanılabilir mi.

## Para birimi alanlarını float'tan integer'a geçirme (v3.0.0)

Önce:
  { "amount": 19.99 }

Sonra:
  { "amount": 1999 }  // en küçük para birimi (kuruş)

Ne değişiyor: `amount` artık hesap para biriminin en küçük biriminde
bir tam sayı. `amount`'ı float olarak okuyan kod, 1 Ekim 2026'dan
itibaren 100 kat çok büyük bir değer okuyacak.

Doğrula: geçişten sonra, 19,99'luk bir ücret `amount: 1999` olarak
okunmalı, `amount: 19.99` olarak değil.

Zaman çizelgesi: v2, 15 Ocak 2027'ye kadar float döndürmeye devam
ediyor. v3, başlangıçtan itibaren tam sayı döndürüyor. Her iki sürüm
de şu anda canlı.

Bu beş şeyin her biri, çağıranın aksi takdirde tahmin etmesi veya desteğe sorması gereken bir soruyu yanıtlar, ve bir geçiş kılavuzunun gerçekte kurtardığı maliyet tam olarak budur.

Kim yazmalı, ve ne zaman?

Değişikliği tasarlayan kişi, gönderildiği anda, bir hafta sonra biletlerden yeniden inşa eden bir destek ekibi değil. Kararı veren kişi, eski davranışın hangi kısımlarına kimsenin güvenmemesi gerektiğini ve hangilerinin kazara bir sözleşme olduğunu bilir; o bağlam olmadan sonradan birinin yazdığı bir kılavuz ya açığı fazla açıklama ya da insanları gerçekten bozan tek uç durumu kaçırma eğilimindedir. Kılavuz ve uyumsuz değişikliği duyuran changelog girişi birlikte yayınlanmalı, giriş onu tekrarlamak yerine kılavuza bağlanmalıdır.

Bu, sürümleme ve API changelog'u ile nasıl ilişkilidir?

Doğrudan: bir geçiş kılavuzu, semantic versioning ve changelog'unuz'daki bir MAJOR girişinin sadece bir cümlede özetlediği şeyin ayrıntılı versiyonudur. Changelog girişi bir değişikliğin uyumsuz olduğunu ve kabaca neyin değiştiğini söyler; geçiş kılavuzu, o girişin taşıması gereken bağlantıdır. API changelog'u: ne yayınlanır ve kim okur geçiş kılavuzunu bir API'nin sürdürdüğü beş belgeden biri olarak listeler, her biri farklı bir soruyu yanıtlar; bu, "A'dan B'ye gerçekte nasıl geçerim" sorusunu yanıtlayan belgedir, ve tam da bu yanıt genellikle bir changelog girişi için çok uzun olduğundan kendi sayfasını hak eder.

Bir geçiş kılavuzu ne kadar süre yayında kalmalı?

En azından eski davranış erişilebilir olduğu sürece, ve idealde ondan sonra da. Üç deprecation bildirimini yok saydıktan sonra on sekiz ay geç geçiş yapan bir çağıran hâlâ kılavuza ihtiyaç duyar, ve eski davranış kapatıldığı gün onu silmek sadece ona en çok ihtiyaç duyanın onu bulamamasını garanti eder. Onu sabit bir URL'de tutun ve sayfayı geri çekmek yerine zaman çizelgesi bölümünü güncelleyin. Stripe'ın kendi yükseltme kılavuzu bu örüntünün herkese açık bir örneğidir: her sürümde güncel tutulan tek bir sayfa, bir sonraki sürüm çıktığı anda eskiyen sürüm başına yeni bir belge yerine. Kendi kılavuzunuz da, bir blog arşivine gömülmek yerine, çağıranın zaten okumakta olduğu dokümanlar kadar bulunabilir bir yeri hak eder.

FAQ

Her uyumsuz değişiklik bir geçiş kılavuzu gerektirir mi? Hayır. Çağıranın sadece changelog girişinden halledebileceği bir değişiklik, açık bir yedeğe sahip tek bir yeniden adlandırılmış alan gibi, ayrı bir kılavuza ihtiyaç duymaz. Birden fazla çağrı noktasını etkileyen veya işlenmiş bir örnek gerektiren bir değişiklik duyar.

Bir geçiş kılavuzu API belgeleriyle mi yoksa changelog'da mı yaşamalı? Belgelerle birlikte, changelog girişinden bağlantı verilerek. Changelog girişi bir abonenin önce gördüğü şeydir; kılavuz, harekete geçmeye karar verdiğinde ihtiyaç duyduğu şeydir, ve çağıranın zaten kullandığı referans materyalinin yanında yer alır.

Bir geçiş kılavuzu ile bir deprecation bildirimi arasındaki fark nedir? Bir deprecation bildirimi bir şeyin kaybolacağını ve ne zamana kadar olduğunu belirtir. Bir geçiş kılavuzu bu konuda ne yapılacağının talimatlarıdır. Bağlantılı bir geçiş kılavuzu olmayan bir deprecation bildirimi, çağırana bunu nasıl karşılayacağını söylemeden bir son tarih verir.

Bir geçiş penceresi sırasında hem eski hem yeni davranış belgelenmeli mi? Evet, mümkünse aynı sayfada, böylece çağıran tam olarak neyin değiştiğini görür, farklı zamanlarda yazılmış iki ayrı belgeden bir araya getirmek yerine.

GitHub Actions için bir changelog kontrolü

Mon, 07 Sep 2026 00:00:00 GMT

Changelog'u elle tutan her ekip aynı olaydan sonra aynı konuşmayı yapmıştır: bir sürüm kayıtsız çıkmıştır, biri neden diye sorar, ve dürüst cevap onu yazacak kişinin hızlı gittiği ve changelog adımının sadece hafızada yaşadığıdır. Changelog otomasyonu bir pipeline'ın güvenle otomatikleştirebileceği ve hâlâ bir kişiye ihtiyaç duyanı ele alır; CI'da bir changelog kontrolü bu sorunun diğer yarısıdır, çünkü yazmayı otomatikleştirmek kimse onu tetiklemekle yükümlü değilse yardımcı olmaz. Çoğu ekip pull request kontrollerini zaten GitHub Actions'ta çalıştırır, bu yüzden bu kontrol de orada yaşar.

"İnsanlardan bir kayıt eklemelerini rica ediyoruz" neden öngörülebilir bir örüntüyle başarısız olur?

Çünkü bir pull request'te her şeyle dikkat için rekabet eder, ve atlamanın anında sonucu olmayan tek parçasıdır. Testler gürültülü başarısız olur ve merge'ü engeller. Eksik bir changelog kaydı hiçbir şeyi engellemez, bu yüzden biri acele ettiği anda kaybeder, ki pratikte bu çoğu zamandır. Hafızayla zorunlu kılınan bir politika beklenecek hızda tam olarak bozulur: herkesin kabul etmesinden sonraki ilk birkaç hafta iyidir, sonra umursayan kişi tatile gidince veya ekip değiştirince sessizce terk edilir.

Bir changelog kaydı için bir CI kontrolü gerçekte neyi doğrular?

Yazının kalitesini değil, sadece bir kaydın var olduğunu ve doğru biçimlendirildiğini, ki bu bir kişinin kafasında değil CI'da çalışan bir changelog kontrolü için doğru kapsamdır. Yaygın bir şekil: kontrol PR'ın diff'ine bakar ve ya bir changeset dizininde yeni bir dosya (Changesets ve benzer araçların kullandığı desen) ya da bir changelog dosyasında değiştirilmiş bir satır ister, ve ikisi de yoksa build'i başarısız kılar. Kaydın gerçekte ne söylediğinin incelemesi hep olduğu yerde olmaya devam eder, code review'da, çünkü o yargı bir script'e ait değildir.

CI kontrolü neyi doğrular	Neyi doğrulamaz
Diff'te bir changeset veya changelog satırı var	İfadenin açık olup olmadığı
Kayıt, bir monorepo'da doğru paketi referans alıyor	Değişikliğin gerçekten bir kayıt hak edip etmediği
Dosya sözdizimsel olarak geçerli (frontmatter, JSON şekli)	Kaydın etki hakkında dürüst olup olmadığı

Her PR'ın buna ihtiyacı var mı, yoksa bazı değişiklikler muaf mı?

Bazıları muaftır, ve muafiyet listesi bu sistemlerin gerçekten kurulduğu veya terk edildiği yerdir. Görünür etkisi olmayan bir bağımlılık güncellemesi, sadece test değişikliği, davranış değişikliği olmayan dahili bir refactor: hiçbiri bir katkıda bulunanı changelog'u okuyan kimsenin umursamadığı bir şey için changelog kaydı uydurmaya zorlamamalı. İşe yarayan desen, bir katkıda bulunanın uygulayabileceği (no-changelog-needed) ve dosyasız CI kontrolünü karşılayan, PR'ı onaylayan kişi tarafından incelenen bir etiket veya bayraktır, böylece muafiyetin kendisi bir kaydın geçeceği aynı incelemeden geçer.

Acil bir hotfix gibi meşru istisnalara ne olur?

Gate merge'e aittir, deploy'a değil: gerçek zaman baskısı altındaki bir hotfix, CI kontrolü bitmiş bir paragraf yerine niyetle karşılansa yeter ki, bir yer tutucu kayıt veya takip bileti ile merge edebilir; bazı ekipler bir bakımcının sonraki sürüm kesiminden önce cilalayacağı tek satırlık bir stub kabul eder. Gate'in asla izin vermemesi gereken şey adımı sessizce atlamaktır, çünkü unutulan bir stub hiç var olmamış bir kayıttan daha küçük bir başarısızlıktır, ve bir stub en azından birinin daha sonra bulabileceği bir iz bırakır.

# .github/workflows/changelog-check.yml
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
jobs:
  changelog:
    if: >-
      !contains(github.event.pull_request.labels.*.name,
      'no-changelog-needed')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # diff için temel dal gerekir
      - name: Require changelog entry
        run: |
          base="origin/${{ github.base_ref }}"
          if ! git diff --name-only "$base"...HEAD \
              | grep -q '^\.changeset/'; then
            echo "No changeset. Add one, or have a maintainer"
            echo "apply the no-changelog-needed label."
            exit 1
          fi

Bu bir monorepo'da aynı şekilde çalışır mı?

Bir parça daha gerektirir: kaydın hangi paket için olduğu. Monorepo changelog'ları tek bir repo çapında dosyanın paketler bağımsız olarak yayınlanmaya başladığında neden çalışmayı bıraktığını ele alır; CI kontrolü aynı gereksinimi devralır; bir paket adlandırmayan bir changeset, doğru changelog'un güncelleneceğine dair yararlı bir kanıt değildir, sadece diff'in bir yerinde bir dosyanın değiştiğinin kanıtıdır. Bunun için kurulmuş araçlar (Changesets JavaScript ekosisteminde yaygın olandır), changeset oluşturulduğu anda katkıda bulunandan etkilenen paketi ve bir semver bump'ını seçmesini ister, böylece CI kontrolü her iki parçayı da sonradan çıkarmak yerine bedava alır.

Kontrolün kendisinin gerçek PR'ları engellemeye başlamadan önce doğru olduğu nereden bilinir?

Önce, kullanıp atacağınız bir dala karşı bir deneme pull request'i açın: biri changeset'li, biri changeset'siz, ve biri muafiyet etiketini taşıyan, ve kontrol başkasının işine uygulanmadan önce üçünün de beklediğiniz sonucu aldığını doğrulayın. Bir koşul tersten yazıldığı için her PR'ı geçiren, fail-open bir changelog kontrolü, hiç kontrol olmamasından daha kötüdür, çünkü var olmayan bir kapsama gibi görünür. Aynı dosya üzerinde workflow_dispatch, birkaç yakın zamanda merge edilmiş PR'a karşı elle çalıştırılınca, canlı bir pull request'e hiç ihtiyaç duymadan bu hataların çoğunu yakalar.

Aynı fikir GitHub Actions dışında da işler mi?

Şekil aynen taşınır, sadece sözdizimi değişir. GitLab CI aynı kuralı bir GitHub Actions if'i yerine $CI_MERGE_REQUEST_LABELS'ı kontrol eden bir job rules bloğu olarak ifade eder, ve zorunlu bir merge request onayı muafiyet inceleme adımının yerini alabilir. Bu makalenin tarif ettiği kontrol GitHub Actions'tır, çünkü onu okuyan çoğu ekip zaten o platformdadır, ama altta yatan gereksinim, rica edilen bir gelenek değil makine tarafından kontrol edilen bir gate, CI'ın bir merge'den önce çalıştığı her yerde aynıdır.

FAQ

CI kontrolü merge'ü engellemeli mi, yoksa sadece uyarmalı mı? Engellemeli. Bir uyarı işlevsel olarak nazikçe rica etmekle aynıdır, ki bu zaten başarısız oldu. Muafiyet etiketi tam olarak gerçek bir sadece-uyarı durumunun aynı katı gate'ten yine de meşru bir yolu olması için var.

Bir muafiyet etiketinin doğru uygulanıp uygulanmadığını kim inceler? Pull request'i onaylayan kişi, zaten yaptığı incelemenin bir parçası olarak. Etiket asla kendiliğinden uygulanıp incelenmeden kalmamalı, yoksa gate'in kapatmak için tasarlandığı aynı sessiz kaçamak haline gelir.

Bunu CI'da zorunlu kılmak bir changelog otomasyon pipeline'ına olan ihtiyacın yerini alır mı? Hayır, onu besler. Changelog otomasyonu yapılandırılmış kayıtları bir sayfaya, akışa ve e-postaya dönüştürmeyi ele alır; CI kontrolü bu yapılandırılmış kayıtların ilk etapta otomatikleştirilmek için var olmasını garanti eden şeydir.

Önce inşa etmeye değer bunun en küçük versiyonu nedir? Belirlenmiş bir changelog dizini altında hiçbir dosya değişmediyse başarısız olan, bir muafiyet etiketiyle tek bir kontrol. Paket bazlı yönlendirme ve bir monorepo için semver çıkarımı daha sonra gelebilir; temel alışkanlık, bir kayıt var ya da biri açıkça gerekmediğini söyledi, ilk günden itibaren sahip olmaya değer olandır.

Müşteriyi kaybetmeden bir özellik talebi nasıl reddedilir

Mon, 07 Sep 2026 00:00:00 GMT

Döngüyü kapatmak genelde birine talebinin gönderildiğini söylemek demektir. Çoğu takip sisteminin hiç süreci olmadığı zor yarısı ise hayır demektir. Çoğu özellik talebi asla gönderilmez, bu da bir ürünün kullanıcılarına gerçekten borçlu olduğu döngü kapatmanın çoğunun bir duyuru değil, bir ret olduğu anlamına gelir, ve kötü ele alınan bir ret sessizliğin maliyet edeceğinden daha fazla iyi niyete mal olur. İyi ele alındığında neredeyse hiçbir şeye mal olmayabilir, çünkü talep eden kişinin çoğu zaman en çok istediği şey duyulduğunu bilmektir, özelliğin kendisi değil.

İyi reddetmek neden iyi göndermek kadar önemli?

Çünkü sessizlik açıklamasız bir ret gibi okunur, ve açıklanmış bir hayır dikkat gibi okunur. Hiçbir şey duymayan kişi ya talebin yok sayıldığını ya da kaybolduğunu varsayar, ve her iki sonuç da ona sormaktan vazgeçmeyi öğretir, ki bu bir ürünün gerçek bir retten elde ettiği aynı sonuçtur, sadece daha yavaş ulaşılır ve yol boyunca daha fazla kırgınlıkla. Açıkça ve bir nedenle hayır diyen bir yanıt, döngüyü gönderilmiş bir özellik kadar tamamen kapatır, ve bunu daha hızlı yapar.

Yanıt	Talep eden kişinin öğrendiği	İlişkiye maliyeti
Sessizlik	Kimse okumadı, ya da kimse umursamıyor	Yüksek, ve her gelecek talep ile birikir
Nedensiz otomatik yanıt	Bir yerde süresiz olarak sırada	Orta; zaman kazandırır ama güven değil
Nedenli ret	Okundu, düşünüldü ve yanıtlandı	Düşük, neden dürüstse
Alternatifli ret	Asıl ihtiyaç gerçekten duyuldu	En düşük; genelde güven inşa eder

Bir reddi kötü hissettiren nedir?

Neredeyse her zaman üç şey, birleşik olarak. Genellik: ne istendiğine gerçekte değinmeyen kalıp "geri bildiriminiz için teşekkürler" hiç okunmamış gibi görünür, okunmuş olsa bile. Gecikme: talep eden kişi sormayı unuttuktan sonra, talepten altı ay sonra gelen bir ret, hızlı bir hayırdan daha kötü hissettirir, çünkü talebin düşünülüp reddedilmek yerine dokunulmadan kaldığını ima eder. Ve dayanmayan bir neden: "yol haritamızda değil" hiçbir şeyi yanıtlamaz, "bu, bu yıl dokunmayı planlamadığımız izin mantığını yeniden tasarlamayı gerektirir" ise talep eden kişiye gerçekten değerlendirebileceği ve yeterince önemliyse yükseltebileceği veya etrafından dolaşabileceği bir şey verir.

İyi bir ret gerçekte ne söylemeli?

Bu sırayla dört şey: genel bir parafraz değil, belirli talebi adlandıran bir onay; dürüst neden daha yumuşak bir bahane yerine "bu, ürünün gittiği yöne uymuyor" olsa bile dürüstçe belirtilen gerçek neden; kapının kapalı mı yoksa şu an sadece açık olmadığı mı, çünkü bunlar çok farklı tonlar gerektirir; ve varsa, tam olarak istenen özellik olmasa bile altta yatan ihtiyacı ele alan bir alternatif.

Merhaba Jamie,

Takım davetleri için toplu CSV içe aktarma eklenmesi talebiniz için
teşekkürler. İnceledik, ve bunu inşa etmeyeceğiz: davet akışımız
güvenlik nedenleriyle her yeni üyenin ayrı ayrı incelenmesine
dayanıyor, ve toplu içe aktarma, kasıtsız değil, tasarım gereği buna
karşı çalışır.

Asıl sorun büyük bir takımı hızlıca davet etmekse, API, incelemeyi
atlamadan neredeyse tüm hızı sağlayan script tabanlı bireysel davetleri
destekliyor: [bağlantı]. Kurmak için yardım isterseniz memnuniyetle
yardımcı olurum.

Bunun bir şablonun yapamayacağı şeyi ne yaptığına dikkat edin: gerçek özelliği adlandırıyor, belirsiz bir politika yerine gerçek bir tasarım kararına bağlı bir neden veriyor, ve sadece bileti kapatmak yerine altta yatan sorunu çözen bir yol sunuyor.

Bu, gönderilmiş bir özellikte döngüyü kapatmaktan nasıl farklı?

Mekanik benzer, ton değil. Müşteriyle geri bildirim döngüsünü kapatmak mesajın iyi haber olduğu ve ana riskin göndermeyi unutmak olduğu gönderilmiş durumu ele alır. Bir ret kötü haberdir, ya da en azından istenmeyen haberdir, ve verilen nedende daha fazla özen ve teslimatta daha az otomasyon gerektirir: gönderilmiş bir özellik bildirimi, bir durum değişikliği tarafından tetiklenen kalıp bir yorum olabilir, ama kalıp gibi okunan bir ret, tam olarak bu yaklaşımın tamamının kaçınmaya çalıştığı başarısızlık biçimidir. İkisi yine de bir gereksinimi paylaşır: orijinal talep talep eden kişiyle bağlantılı kalmalıdır, özellik talebi takibinin ele aldığı aynı takip disiplini, yoksa her iki mesajı da bireysel olarak gönderecek bir yol yoktur.

Bir ret, herkese açık bir yol haritasındaki bir durum gibi herkese açık olmalı mı?

Genellikle durum öyle olsa bile belirli neden değil. Herkese açık yol haritası talep eden kişinin tekrar sormadan kontrol edebileceği durum etiketlerini ele alır, ve bir "reddedildi" veya "planlanmadı" durumu o sistemin parçası olabilir. Ama özellikle dahili öncelikleri veya pek de gurur verici olmayan bağlamı içeren ayrıntılı neden, genellikle herkese açık bir durum sayfasından çok bireysel yanıtta daha değerlidir, orada aynı ifade gerçekten soran tek kişi yerine her okuyucu için işe yaramak zorundadır.

Reddedilen her talep bireysel bir yanıtı hak eder mi?

İsimli, ulaşılabilir bir kişiden gelen her talep hak eder, en azından kısa bir tane. Yüksek hacimli, tekrar eden veya anonim talepler istisnadır: benzer talepleri gruplandırıp grup başına bir kez yanıtlamak, veya paylaşılan bir durum etiketini güncellemek, bireysel yanıtlar gerçekten ölçeklenmediğinde makuldür. Tutulması gereken sınır, "herkese bireysel olarak yanıt veremeyiz"in gerçek hacme karşı kontrol edilen gerçek bir operasyonel kısıtlama olması gerektiğidir, iki dakika sürecek bir yanıtı atlamak için varsayılan bir bahane değil.

FAQ

Zayıf bir nedenle hızlıca reddetmek mi, yoksa iyi bir tane için zaman ayırmak mı daha iyi? Dürüst bir nedenle hızlıca, ikisini de tek başına geçer. Gerçek bir nedenle, kısa bile olsa, hızlı bir yanıt, cilalı bir nedenle yavaş bir yanıtı geride bırakır; gecikmenin kendisi güveni zedeleyenin parçasıdır.

Bir ret talebin daha sonra yeniden değerlendirileceğini vaat etmeli mi? Sadece bu gerçekten olasıysa ve onu gerçekten yeniden değerlendirmek için bir mekanizma varsa, mesela bir planlama döngüsünde onu yeniden yüzeye çıkaran bir etiket gibi. Böyle bir mekanizma olmadan belirsiz bir "aklımızda tutacağız", işlevsel olarak sessizlikle aynıdır, sadece daha kibarca ifade edilmiş.

Dürüst neden şirketin paylaşamayacağı bir şeyse, rekabet endişesi gibi? Daha yumuşak bir neden uydurmak yerine bunu doğrudan söyleyin. "Buradaki belirli gerekçeyi paylaşamıyoruz, ama bu inşa etmeyi planladığımız bir şey değil", takip sorusu karşısında çöken uydurma bir açıklamadan daha dürüst, ve daha saygı görür.

Bir talebi reddetmek, takipten silinmesi gerektiği anlamına mı gelir? Hayır. Onu, nedenle birlikte reddedildi olarak etiketlenmiş şekilde saklayın, böylece bir sonraki benzer talebin karşı gruplandığı örüntünün parçası olur, ve daha sonra değişen bir bağlam (yeni bir entegrasyon, yeni bir takım önceliği) değerlendirmeyi sıfırdan başlatmak yerine onu yeniden yüzeye çıkarabilir.

Feature flag release notları: ne söylenir, ne zaman

Mon, 07 Sep 2026 00:00:00 GMT

Bir özellik talebinde döngüyü kapatmak, şeyin teslim edildiği net bir an olduğunu varsayar. Bir feature flag bu anı ortadan kaldırır, ve feature flag release notlarının zamanlamasını zorlaştıran da budur. Kod merge edilir, flag var olur, ve günler ya da haftalar boyunca özellik aynı anda hem canlıdır hem de onu isteyebilecek neredeyse herkes için görünmezdir, sıklıkla bunu ilk başta isteyen kişi de dahil. Çok erken haber vermek onu henüz orada olmayan bir özelliğe götürür. Çok geç haber vermek, güven inşa etmesi gereken döngünün unutulmuş gibi okunmasına neden olur.

Bir flag olağan "teslim et, haber ver" sırasını neden bozar?

Çünkü bir olayı en az ikiye böler: kodun canlıya çıkması, ve flag'in belirli bir hesap için açılması. Bir geri bildirim döngüsünü kapatmanın her süreci bunların birlikte gerçekleştiğini varsayar, ki bu çoğu sürüm için doğru ve aşamalı yayılım, hedefleme ya da acil kapatma anahtarı olarak kullanılan bir flag'in arkasındaki her şey için yanlıştır. Müşteri geri bildirim döngüsünü kapatmak isteyen kişiye tam olarak bir changelog girişi onaylanıp yayınlandığı anda haber vermeyi tarif eder; bu adım, girişi yayınlamak ile özelliğin kullanılabilir olması aynı an olduğunda için yazılmıştır, ve bir flag tam olarak bunların aynı olmadığı durumdur.

An	Ne doğru	İsteyen kişiye şimdiden haber verilmeli mi
Kod merge edildi, flag her yerde kapalı	Özellik var, kimse kullanamıyor	Hayır
Flag isteyen kişinin hesabı için açık	Özellik var, o kişi özellikle kullanabiliyor	Evet
Flag onu dışlayan bir yayılım yüzdesi için açık	Özellik var, o kişi hâlâ kullanamıyor	Hayır
Flag tamamen kaldırıldı, özellik sadece açık	Özellik herkes için var	Evet, henüz haber verilmediyse

Birine ne zaman haber verileceğine dair gerçek kural nedir?

Flag hesabı için açık olduğunda haber ver, kod merge edildiğinde değil ve flag oluşturulduğunda değil. Bu tek kural yukarıdaki tablonun her satırını kapsar, çünkü bildirimi isteyen kişi için gerçekten önemli olan tek gerçeğe bağlar: şu anda gidip o şeyi kullanabilir mi. Merge'e ya da flag'in oluşturulmasına bağlı bir bildirim aslında bir mühendislik ilerleme raporudur, ve bir özellik isteyen kişi ilerleme raporu istemez, ne zaman bakacağını bilmek ister.

Bu, isteyen kişinin erken veya özel erişime ihtiyacı olduğu anlamına mı gelir?

Mutlaka değil, ve bunu zorlamak kendi sorununu yaratır. Flag yük veya kararlılık nedenleriyle aşamalı olarak yayılıyorsa, bir hesabı sadece döngüyü daha hızlı kapatmak için sıranın başına taşımak, yayılımın kademeli olmasının nedenini baltalar. Dürüst seçenekler şunlardır: isteyen kişinin hesabının yayılıma doğal olarak ulaşmasını beklemek ve o zaman haber vermek, ya da, aciliyet bunu haklı çıkarıyorsa, yayılımın sahibi olan kişinin gerçek bir kararı olarak bilinçli şekilde onu erken açmak, bir bildirim gönderme isteğinin yan etkisi olarak değil.

Ya flag bir yayılım mekanizması değil de acil kapatma anahtarıysa?

O zaman güvenli varsayım tersine döner. Bir özelliği yayılımını kademelendirmek yerine hızlıca kapatabilmek için var olan bir flag genelde özelliğin oluşturulduğu anda tamamen canlı olması gerektiği anlamına gelir, ve flag sıralama yerine güvenlik için vardır. Bu durumda, isteyen kişiye deploy anında haber vermek doğrudur, flag'siz herhangi bir sürümde olduğu gibi; flag'in varlığı döngünün ne zaman kapandığını değiştirmemesi gereken operasyonel bir ayrıntıdır. Önemli olan ayrım flag'in ne için olduğudur, birinin var olup olmadığı değil.

Flag, feature flag release notlarının ne söylemesi gerektiğini değiştirir mi?

Ne zaman yayınlandığını değiştirir, neyi içerdiğini değil. Flag hesapların %100'ü için açık olduğu tam anda yayınlanan bir giriş, tam olarak normal bir changelog girişi gibi okunur, ve öyle olmalı; onu daha sonra bulan bir okuyucunun bir flag'in hiç işin içinde olduğunu bilmesi için hiçbir nedeni yoktur. Yapmaması gereken şey, flag sadece küçük bir yayılım yüzdesi için açıkken yayınlanmaktır, çünkü genel bir changelog girişi onu okuyan herkesi, flag'i olmayan hesaplar dahil, bulamayacakları bir özelliği aramaya gönderir, ki bu aynı sorunun daha kötü bir versiyonudur, tek bir isteyen kişinin ölçeğinde değil ürün genelinde. Bu zamanlama kuralı, feature flag release notları ile sıradan bir giriş arasındaki tüm farktır: içerik aynıdır, sadece yayın tarihi değişir. Release notes nasıl yazılır burada da geçerli olan "hiçbir eylem gerekmiyor" disiplinini ele alır: okuyuculara bunun onları etkileyip etkilemediği söylenmeli, sadece bir yerde var olduğu değil.

Ürün güncelleme e-postaları flag'li bir özelliği farklı ele almalı mı?

Evet, çoğunlukla yeniden yazmak yerine erteleyerek. Ürün güncelleme e-postası şablonu hedeflenmiş bildirimleri geniş özetlere karşı ele alır; flag'li bir özellik, hedeflenmiş bir bildirimin zamanlamasının gönderilmeden önce alıcının kendi flag durumuna karşı kontrol edilmesi gereken bir durumdur, ki bu bir geniş özetin hiç kolayca yapamayacağı bir şeydir, bu da hâlâ yayılımın ortasındaki her şey için bir özetin neden yanlış kanal olduğuna dair bir neden daha.

FAQ

Flag var olduğu ama isteyen kişi için henüz açık olmadığı zaman ona özelliğinin "yakında geliyor" olduğu söylenmeli mi? Sadece gerçek, yakın bir tarih varsa, ve o zaman bile ölçülü şekilde. Tarihsiz bir "yakında", yeterince zaman geçtikten sonra tam olarak sessizlik gibi okunur, ve izlenmesi ve tutulması gereken ikinci bir söz yaratır.

Bir flag'in döngüyü kapatacak kadar ilerlediğine kim karar verir? Bildirimin sahibi değil, yayılımın sahibi. Yayılımı olan kişi "hesapların %100'ü"nün yakın mı yoksa hâlâ haftalar uzakta mı olduğunu bilir; döngüyü kapatma adımını sabit bir takvim tarihine değil onun durumuna bağlamak bildirimi dürüst tutar.

Kalıcı bir flag arkasındaki (hiç tamamen kaldırılmayan) bir özellik hiç genel bir changelog girişi alır mı? Evet, o ürün için "genel kullanıma açık" ne anlama geliyorsa ona ulaştığında, flag'in kendisi operasyonel nedenlerle sonsuza kadar kodda kalsa bile. Changelog girişi okuyucu için erişilebilirlikle ilgilidir, o erişilebilirliğin nasıl gerçekleştirildiği uygulama detayıyla değil.

Ya flag kaldırılır ve özellik teslim edilmek yerine öldürülürse? Bu bir ret, teslimat bildirimi değildir, ve başka herhangi bir ret kadar özen hak eder. Bir özellik talebi nasıl reddedilir o mesajın ne söylemesi gerektiğini ele alır; döngüyü dürüstçe kapatmak bazen onu bir hayırla kapatmak anlamına gelir.

Feature flag release notları normal bir girişten farklı bir şablona mı ihtiyaç duyar? Şablon değişmez, sadece yayından önce bir kapı adımı eklenir: kodun sadece merge edildiğine değil, soran hesap için flag durumuna bakın, ve bu kontrol geçene kadar girişi bekletin. Girişle ilgili geri kalan her şey, ifade, uzunluk, FAQ disiplini, diğer her release notu kadar aynı kalır.

Özellik taleplerini kaybetmeden takip etmek

Mon, 07 Sep 2026 00:00:00 GMT

Özellik talebi takibi neredeyse her zaman iki şekilden birinde başarısız olur. Ya taleplerin gidecek hiçbir yeri yoktur, bu yüzden gelen kutularında ve Slack konularında yaşarlar ve tek tek unutulurlar, ya da kimsenin bir daha bakmadığı bir yerleri vardır ve topluca unutulurlar. İşe yarayan bir sistem her iki başarısızlığa da dayanmalıdır: her talebin düştüğü tek bir yere ve o yeri gelecek ay tekrar açmak için bir nedene ihtiyaç vardır.

Özellik talepleri gerçekte nereden gelir?

Çoğu takip sisteminin hesaba kattığından daha fazla kanaldan. "Şöyle olsa iyi olur" içeren bir destek bileti. Herkese açık bir yol haritasındaki bir yorum. Bir potansiyel müşterinin anlaşmayı engelleyen tek şeyi adlandırdığı bir satış görüşmesi. Ürün içindeki bir widget. Her kanalın kendi sahibi ve kendi araçları vardır, ve talepler tam da bu yüzden dağılır: destek bilet kuyruğu ile ürün ekibinin backlog'u nadiren aynı sistemdir, ve sadece ikisinden birine ulaşan bir talep, pratikte sadece tek bir departmana ulaşmıştır.

Kaynak	Tipik sahip	Genelde nerede kaybolur
Destek biletleri	Destek ekibi	Çözüldü olarak kapatılır, bir daha gündeme gelmez
Satış görüşmeleri	Satış / hesap yönetimi	Üründe kimsenin okumadığı bir CRM alanı
Üründeki widget	Ürün	Takip edilmeyen bir form gönderimi
Yol haritası yorumları	Yol haritasını kim inşa ettiyse	Yorum dizisinin kendisi
Sosyal medya / yorumlar	Pazarlama ya da hiç kimse	Bir kere ekran görüntüsü alınır, sonra kaybolur

Her kanal için tek bir alım formu işe yaramaz, çünkü kimse onu benimsemez. İşe yarayan şey, yönlendirme başta otomatikleşene kadar günde beş dakikalık kopyala yapıştır olsa bile, her kanalın aktığı tek bir hedeftir.

Özellik talebi takibini gerçekte ne bozar?

Neredeyse her zaman iki şey. Birincisi, eksik bir hedef: talepler geldikleri kanalda yanıtlanır ve hiçbir yerde kalıcı olarak kaydedilmez, bu yüzden üç farklı müşteriden gelen aynı talep, bir sinyal yerine üç ilgisiz tekil yanıt gibi görünür. İkincisi, daha yaygın olanı, dolup okunmayı durduran bir hedeftir. Filtrelenmemiş 400 satırlık bir e-tablo artık bir takip sistemi değildir; tesadüfen yazılabilir olan bir arşivdir.

İkinci başarısızlık daha tehlikelidir, çünkü takibin çalışıyormuş gibi görünmesini sağlar. Talepler kaydedilir. Biri "kaç kişi X'i istedi" diye sorana kadar hiçbir şey bozuk görünmez, ve dürüst yanıt "bunu bilmek için 400 satırın hepsini okumamız gerekir" olur.

Bir özellik talebi gerçekte neyi kaydetmeli?

Orijinal mesajı yeniden okumadan sonradan üç soruyu yanıtlayacak kadar: ne istendiği, mümkünse talep edenin kendi kelimeleriyle; kimin istediği, ve yanıt "onu inşa ettik" olursa ona nasıl ulaşılacağı; ve bunun yaygın bir istek mi yoksa tek seferlik bir vaka mı olduğunu bilmek için ne gerektiği. Doğrudan bir alıntı bir parafrazdan daha değerlidir, çünkü talebi kim triyaj ettiyse onun yazdığı parafraz zaten kendi okumasını taşır, ve altı ay sonra ikinci bir kişinin doğrulayamayacağı da tam olarak o okumadır.

Hangi etiketler işe yarar?

İki tane, ve farklı soruları yanıtlarlar. Bir tür etiketi, bir özellik talebini bir hata raporundan ayırır, çünkü ikisi de farklı sahiplere ve zaman çizelgelerine ihtiyaç duyar, ve ikisini tek bir kuyrukta karıştırmak en yüksek sesli şikayetlerin talepleri geçmesine izin verir. Low, medium ve high gibi küçük bir kümeyle sınırlı bir öncelik etiketi, "birinin ürünü kullanmasını engelliyor" ile "güzel olurdu"yu ayırır, çünkü ikisi de çok farklı yanıt süreleri hak eder ve hiçbiri diğerinin temposunu devralmamalıdır. Tür etiketini doğru koymak, talebin iddia ettiği şey olduğunu varsayar; bir özellik talebi gerçekte bir hata raporu olduğunda bir müşterinin kendi sözlerinin bu etiketi yanlış yöne işaret ettiği durumu ele alır.

Otomatik triyaj, talep geldiği anda ikisini de uygulayabilir. changeloop'ta, bir widget gönderimi aynı geçişte feature-request veya bug etiketini ve bir priority:low|medium|high etiketini alır, artı öğeyi açmadan kaynağın görünür olması için bir from-widget etiketi. Bu, backlog'u bir öğleden sonra yerine bir dakikada filtrelenebilir kılmaya yeter: bu ay widget'tan gelen her yüksek öncelikli özellik talebini bana göster.

Herkese açık bir yol haritası olduğu anda üçüncü bir etiket işe yarar: talep edenin kendi başına kontrol edebileceği bir durum. Herkese açık yol haritası, planned, building ve shipped durumlarını baştan sona ele alır; kısacası bu etiket, özel bir kuyruğu, talep edenin tekrar sormadan kontrol edebileceği bir şeye dönüştürür.

Sırada ne inşa edileceğine nasıl karar verilir?

Saymadan önce grupla. Aynı temel yeteneği farklı şekillerde ifade eden on talep, bir e-tabloda dağınık on satır gibi görünür, gruplandığında ise güçlü bir sinyal gibi görünür, ve bu gruplama genelde eksik olan adımdır, sayma değil. Gruplama olmadan ham bir sayı, arkasında gerçek talebi en çok olanı değil, en akılda kalıcı isme sahip özelliği ödüllendirme eğilimindedir.

Kaç kişinin istediğine göre değil, kimin istediğine göre ağırlıklandır. Yenilemeye yakın bir hesaptan gelen bir talep, bir deneme kaydından gelen aynı talepten farklı bir aciliyet taşır, ve bu bağlamı çıplak bir sayı lehine atan bir takip sistemi, en yararlı sayı yerine hesaplanması en kolay sayı için optimize eder.

Buradaki her karar aynı zamanda kaybeden talepler de üretir, ve onlar da bir yanıtı hak eder; bir özellik talebi nasıl reddedilir isteği kabul edilmeyenlere ne söyleneceğini ele alır. Gruplama ve ağırlıklandırma, "sırada ne inşa edilecek" sorusunun sadece yarısıdır; özellik taleplerine öncelik vermek gerçek çerçeveleri, RICE'ı, gelire göre ağırlıklandırmayı ve ham sayıları, ve her birinin nerede kırıldığını ele alır.

Bir şey gönderildiğinde döngü nasıl kapatılır?

Bu, takip sistemlerinin en sık atladığı adımdır, ve talep edenlerin gerçekten fark ettiği adımdır. Müşteriyle geri bildirim döngüsünü kapatmak mekaniği baştan sona ele alır; buraya ait olan kısım, döngüyü kapatmanın sadece orijinal talep talep edene bağlı kaldığında işe yaramasıdır. Bir GitHub issue'sundan inşa edilmiş, talep edenin kimliği bir yoruma gömülü olmak yerine issue'ya bağlı olan bir özellik talebi şablonu, birinin göndermeyi hatırlaması gereken bir bildirim yerine otomatik bir "gönderildi" bildirimini mümkün kılan şeydir. Özellik talebi şablonu somut şablonu ve her alanın ne için olduğunu gösterir.

FAQ

Özellik talebi takibi için hangi aracı kullanmalıyım? Ekibin zaten her gün kontrol ettiği şey, kimsenin açmadığı özel bir aracı geçer. Mühendislik zaten orada yaşıyorsa bir GitHub issue tracker'ı iyi çalışır; ürün orada yaşıyorsa hafif bir pano iyi çalışır. Araç, tekrar açılıp açılmadığından daha az önemlidir.

Özellik taleplerinin kopyalanmasını nasıl önlerim? İfadeye göre triyaj etmeden önce temel yeteneğe göre grupla. Yeni bir tane oluşturmadan önce mevcut taleplerde arama yapmak çoğu kopyayı yakalar; aylık bir gruplama geçişi geri kalanını yakalar. Yinelenenleri orijinal sesi kaybetmeden birleştirmek, gruplamanın kendisi bittikten sonra ifadeyle ne yapılacağını ele alır, böylece birleştirme talebi sessizce hangi gönderim önce geldiyse ona daraltmaz.

Her özellik talebi bir yanıt almalı mı? Her biri, kısa bile olsa, bir alındı bildirimi almalıdır, ama her birinin hemen bir karara ihtiyacı yoktur. Talep edenin kendi başına kontrol edebileceği bir yol haritası etiketi gibi görünür bir durum, bir ekibin aksi halde borçlu olacağı bireysel yanıtların çoğunun yerini alır.

Özellik talebi takibi ile herkese açık bir yol haritası arasındaki fark nedir? Takip, asla gönderilmeyecek olanlar da dahil, her isteğin dahili kaydıdır. Herkese açık bir yol haritası, bir ekibin herkese açık olarak taahhüt ettiği alt kümedir, talep edenin tekrar sormadan görebileceği bir durumla birlikte.

Bir özellik talebi gerçekte bir hata raporu olduğunda

Mon, 07 Sep 2026 00:00:00 GMT

"Export limitini artırmak için bir ayar ekleyebilir misiniz?" bir özellik talebi gibi okunur, ve çoğu triyaj sistemi onu anında öyle etiketler. Bazen öyledir. Bazen export, dokümante edilmiş limitten daha düşük bir sayıda bir hata yüzünden başarısız olur, ve kodu göremeyen müşteri tanımlayabildiği en makul çözümü uydurmuştur: bana daha büyük bir sayı verin, belki çalışır. Hangi etiketler işe yarar bir backlog'u özellik talepleri ve hatalara bölen tür etiketini ele alır; burası bir müşterinin kendi sözlerinin etiketi yanlış yöne işaret ettiği durumdur, ve yanlış anlamanın bedeli, altına bakıldığında kimsenin gerçekten istemediği taleplerle dolu bir backlog'a yavaş bir sürüklenmedir.

Gerçekte bir hata raporu olan bir özellik talebi neye benzer?

Sorunu değil, bir workaround'u adlandırır. Gerçek bir özellik talebi genellikle ürünün hiç desteklemediği bir sonucu tanımlar: "bunu daha sonraya planlayabileyim", "koyu mod ekleyin". Yanlış sınıflandırılmış bir hata raporu, eksik bir ayar gibi görünen ama gerçekte bir belirti olan belirli bir sayı, eşik veya davranış tanımlar: "timeout'u artırın", "bir yeniden deneme seçeneği ekleyin", "aynı anda daha fazla satır export etmeme izin verin". Belirti, isteyen kişinin bir hedef tanımlamak yerine bir uygulama, bir ayar, bir anahtar, bir geçersiz kılma önermesidir, çünkü özelliği dokümante edildiği gibi zaten denemiştir ve dokümantasyonun yapması gerektiğini söylediği şeyi yapmamıştır.

Sinyal	Özellik talebi	Özellik talebi kılığındaki hata
İsteyenin tanımladığı şey	Ürünün yapamadığı bir sonuç	Değiştirmek istediği bir parametre
Dokümante edilmiş davranış bunu zaten kapsıyor mu	Hayır, gerçekten eksik	Evet, ama dokümante edildiği gibi çalışmıyor
Daha fazla çaba talebi ortadan kaldırıyor mu	Hayır	Bazen, hata eşiğe bağlıysa
Nereye yönlendirilmeli	Ürün backlog'u	Hata kuyruğu

Bu neden göründüğünden daha önemli?

Çünkü iki kuyruğun farklı sahipleri, zaman çizelgeleri ve başarı kriterleri vardır, ve özellik talebi olarak dosyalanmış bir hata, özellik taleplerine karşı önceliklendirilir, bir hatanın hak ettiği zaman çizelgesinde düzeltilmek yerine gerçek ürün eksiklikleriyle dikkat için rekabet eder. Özellik taleplerini takip etme hataları ve özellikleri tek bir kuyrukta karıştırmanın en yüksek sesli şikayetlerin gerçek talepleri geçmesine nasıl izin verdiğini ele alır; gizlice bir hata olan bir özellik talebi tersi zararı verir, ürün backlog'unda kalır ve temel hata düzeltilir düzeltilmez ortadan kalkacak bir "özellik" için oy toplar, ki bu o backlog'u okuyan herkes için önceliklendirme sinyalini boşa harcar.

Müşterinin kendi sözleri yanlış yöne işaret ettiğinde fark nasıl anlaşılır?

Ne eklemenizi istediğini değil, ne olmasını beklediğini sorun. "Export 500 satırda tıkandı ve 2.000'e ihtiyacım var, limiti artırabilir misiniz" takip sorusu, "500 dokümante edilmiş limit mi", dokümante edilmiş sayının 5.000 olduğunu ve export'un erken başarısız olduğunu ortaya çıkarana kadar bir limit artırma özellik talebi gibi görünür. Sadece bu tek soru, ne beklediği ile ne olduğu, sınıflandırma işinin çoğunu yapar, çünkü gerçek bir özellik talebinin altında kaldığı dokümante edilmiş bir davranış yoktur; beklenecek bir şey yoktur çünkü yetenek henüz mevcut değildir.

Destek görevlileri mi yoksa mühendisler mi bu kararı vermeli?

Destek görevlileri ilk geçişi yapar, çünkü bileti önce onlar görür, ama etiket kolayca değiştirilebilir ve yanlış yapması ucuz olmalı, öğeyi sonsuza dek yanlış kuyrukta sabitleyen tek seferlik bir karar değil. Hafif bir ikinci kontrol, gizli bir hata gibi kokan her şey için haftada bir yeni "özellik talebi" etiketlerini tarayan bir mühendis, kod tabanı bağlamı olmayan bir destek görevlisinin fark edemeyeceği olanları yakalar. Bunun resmi olması gerekmez; bir inceleme sürecinden çok beş dakikalık bir bakıştır.

Gerçek hata bulunduğunda döngüyü kapatmak değişir mi?

Evet, ve gönderebileceğiniz mesajı iyileştirir. Müşteri geri bildirim döngüsünü kapatma bir şey gönderildiğinde isteyen kişiye söylemeyi ele alır; yeniden sınıflandırılmış bir hata bu mesajın daha iyi bir versiyonunu alır, çünkü "bunun arkasındaki hatayı bulduk ve düzelttik" yeterlilik gibi geliyorken, "istediğiniz özelliği oluşturduk" sadece kazara doğru olurdu, çünkü gerçek özellik talebi, gerçekten daha yüksek bir export limiti, hata gittikten ve orijinal 5.000 satır limit yeterli olduktan sonra hiç oluşturulmayabilir.

Yanlış sınıflandırma hiç fark edilmezse ne olur?

Backlog gerçek talep gibi görünen ama olmayan taleplerle dolar, ve o backlog'a karşı alınan önceliklendirme kararları çarpıklığı miras alır. Kırk oylu bir "özellik" gerçekte aynı hataya denk gelen kırk kişi olabilir, ve harfi harfine isteği inşa etmek, gerçekte hiç kısıtlama olmamış bir limiti artırmak için bir ayar, hiçbir şeyi düzeltmeyen karmaşıklık teslim eder, temel hata ise bu konuyu henüz bulmamış müşterilerden yeni "özellik talepleri" üretmeye devam eder.

FAQ

Her özellik talebini bilinen hatalara karşı kontrol etmek için resmi bir adım eklemeye değer mi? Resmi bir adım değil, bir alışkanlık: yeni bir özellik talebini triyaj eden kişi etiketi uygulamadan önce "dokümante edilmiş davranış bunu zaten yaptığını iddia ediyor mu" diye sormalı, çünkü sadece bu soru süreç yükü eklemeden yanlış sınıflandırmaların çoğunu yakalar.

Ya hata bulunduktan sonra bile müşteri bunun bir özellik talebi olduğunda ısrar ederse? Ne bulduğunuzu ve hata düzeldikten sonra önerdiği ayara neden artık ihtiyaç olmayacağını açıklayın. Çoğu müşteri bir workaround ister çünkü gerçek düzeltmenin mevcut olmadığını varsaymıştır, o ayarı özellikle istediği için değil.

Yeniden sınıflandırılmış bir öğe özellik talebi olarak topladığı oyları veya yorumları kaybeder mi? Görünür şekilde saklamalı, çünkü o oylar hatayı bulmaya götüren kanıttır, ve o izi gizlemek aynı yanlış sınıflandırmanın bir sonraki seferde, farklı bir bilette, fark edilmesini zorlaştırır.

Bu tersine de olabilir mi, gerçekte özellik talebi olan bir hata raporu? Daha az sıklıkta, ama evet: "bu bozuk" bazen "bu, yapacağını varsaydığım şeyi yapmıyor" anlamına gelir, ki bu bir kusur değil, eksik bir yetenektir. Aynı soru, ne beklediği ile ne dokümante edildiği, bu yönde de sınıflandırır.

Destek biletleri vs. özellik talepleri: hangisi?

Mon, 07 Sep 2026 00:00:00 GMT

Bir özellik talebi panosu, kullanıcıların oturup ne istediklerini anlatacak zamanları olduğunda neyi talep ettiklerini yakalar. Bir destek bileti, kullanıcıların şu anda neyde takıldığını yakalar, genellikle sinirli, genellikle altta yatan talebi düzgünce tanımlayacak kelime dağarcığı olmadan. İkisi de gerçek sinyaldir, ve sadece birine bakan ekipler, her kanal sistematik olarak farklı bir kullanıcı türünü ve farklı bir ihtiyaç türünü fazla temsil ettiği için sonunda kendinden emin bir şekilde yanlış sorunu çözer. Özellik taleplerine öncelik vermek zaten panoda olanı sıralamayı ele alır; bu yazı panoya hiç ulaşan ile sadece bir destek bileti olarak ortaya çıkan arasındaki boşlukla ilgilidir.

Aynı altta yatan sorun neden bir kanalda ortaya çıkıp diğerinde çıkmaz?

Çünkü iki kanalın farklı aktivasyon maliyetleri vardır, ve bu maliyetin büyüklüğü kimin onu aşacağını belirler. Bir özellik talebi göndermek inisiyatif gerektirir: bir kullanıcının talebi dile getirmeye değer olduğuna inanması, panoyu bulması, ve tutarlı bir şey yazması gerekir, ki bu zaten ürüne yatırım yapmış ilgili, sabırlı kullanıcıları seçer. Bir destek bileti göndermek buna kıyasla neredeyse hiç inisiyatif gerektirmez, çoğunlukla bir görev ortasında sadece "yardım"a tıklamaktır, ki bu, panoyu asla kullanmayacak olanlar dahil, anlık öfkeli kullanıcıları yakaladığı anlamına gelir. Üründeki gerçek bir boşluk, ona rastlayan kullanıcılar resmi bir talep göndermeye en az eğilimli olanlar olduğu için özellik panosunda görünmez ve destekte gürültülü olabilir.

Eksik bir özellik için bilet hacmi, onun için oy sayısıyla aynı şeyi mi ifade eder?

Hayır, çünkü farklı koşullar altında farklı popülasyonları ölçerler. Yüz oylu bir özellik talebi, mevcut bir talebi bulup destekleyecek zamanı ayırmış yüz kişiyi temsil eder, ki bu kalıcı, düşünülmüş talebin güçlü bir sinyalidir. Aynı dönemde gönderilen aynı altta yatan boşlukla ilgili yüz destek bileti, muhtemelen şu anda bir duvara çarpan kullanıcıları temsil eder, ki bunlardan bazıları acil sürtünme geçtikten sonra bunu tamamen unutabilirdi. İkisini "yüz kişi bunu istiyor" şeklinde eşdeğer bir sinyal olarak ele almak, bilet hacmini fazla ağırlıklandırır, çünkü biletler üretmesi ucuzdur ve oylar değildir.

Özellik talebi panosu	Destek biletleri
Göndermek için inisiyatif gerektirir	Neredeyse hiç gerektirmez
Düşünülmüş, kalıcı talebi yakalar	Anlık öfkeyi yakalar
İlgili, sabırlı kullanıcılara eğilimlidir	Panoyu asla kullanmayacak kullanıcıları yakalar
Bir oy sayısı gerçek bir bağlılık sinyalidir	Bir bilet sayısı sürtünmeyi yansıtır, her zaman isteği değil

Bir özelliğin destek bileti olup panoda neredeyse hiç oyu olmaması ne anlama gelir?

Genellikle, talebin var olduğu ama ona rastlayan kullanıcıların panonun var olduğunu bilmediği, oylamanın bir şey değiştireceğine inanmadığı, veya sorunla resmi olarak kaydetmek için kanal değiştirmekle uğraşamayacak kadar nadiren karşılaştığı anlamına gelir. Bu tam olarak bir talep panosunun yapısal olarak kaçırdığı popülasyondur, ve buradaki düşük oy sayısı düşük talebin değil, bir ölçüm boşluğunun kanıtıdır. Eksik bir özellik etrafındaki destek bileti kümesini, biletlere güvensizlik göstermek yerine, kullanıcılar adına kendinizin panoya kaydettiği kendi sinyali olarak ele alın, böylece sadece oy sayılarına göre önceliklendiren kişi için görünmez kalmaz.

Pano düşük öncelik olarak okunur:
"Export to CSV": 6 ayda 4 oy

Destek farklı bir hikaye anlatır:
"Export to CSV": aynı dönemde, her biri farklı bir
hesaptan, her biri "şu anda desteklenmiyor, geri
bildirimi ileteceğiz" ile kapatılan 31 bilet

Destek biletlerindeki bir artış her zaman altta yatan sorunun eksik bir özellik olduğu anlamına mı gelir?

Hayır, ve iki kanalın ters yönde yanıltabileceği yer burasıdır. Bir bilet artışı, zaten var olan bir özellik etrafındaki kafa karıştırıcı bir arayüzden, bir hatadan, veya yeterli açıklama olmadan çıkan bir değişiklikten eşit derecede sık kaynaklanır, ve bunların hiçbiri yeni bir şey inşa ederek çözülmez. Her bilet artışını "kullanıcılar sahip olmadığımız bir özelliği istiyor" olarak okumak, aslında dokümantasyon boşlukları veya kılık değiştirmiş kullanılabilirlik sorunları olan şeylerle dolu bir roadmap üretir. Destek bileti size sürtünmenin nerede olduğunu söyler; çözümün yeni bir özellik mi, bir arayüz değişikliği mi, yoksa daha iyi bir yardım makalesi mi olduğunu tek başına söylemez, ve bunu karıştırmak mühendislik zamanını yanlış çözüme harcar.

Ne inşa edileceğine karar verirken iki sinyal gerçekte nasıl birleştirilmeli?

Sürtünmenin nerede olduğunu bulmak için biletleri kullanın, ve gerçekten istenen sonucun neye benzediğini doğrulamak için, pano zayıf olduğunda doğrudan iletişim ile birlikte talep panosunu kullanın. Bir bilet kümesi gerçek, hissedilen bir sorunu tanımlar; çözümü üzerine inşa edecek kadar kesin bir şekilde nadiren belirtir, çünkü bir destek konuşmasındaki öfkeli bir kullanıcı belirtileri tanımlar, spesifikasyonları değil. Talep panosu, aynı altta yatan sorun üzerinde yeterli oy olduğunda, "bu gerçekte neyi tatmin ederdi" detayının daha fazlasını taşıma eğilimindedir, çünkü bir talep yazmak zaten neyin yanlış olduğunu bildirmek değil, ne istendiğini belirtme eylemidir.

Destek temsilcileri biletleri kendileri özellik talebi olarak kaydetmeli mi?

Evet, ve bu iki kanal arasındaki boşluk için en yüksek kaldıraçlı tek düzeltmedir. Bir bileti gizli bir özellik talebi olarak tanıyan bir temsilci, sadece çözüp devam etmek yerine, onu müşteri adına panoya kaydedebilir, ki bu, müşterinin ikinci bir kanalı keşfedip kullanmasını gerektirmek yerine ölçüm boşluğunu doğrudan kapatır. Bu sadece kaydetmenin temsilci için dakikalar değil saniyeler sürmesi durumunda işe yarar, böylece bunu yapmanın sürtünmesi biletle basitçe ilgilenip bir sonrakine geçmenin sürtünmesinden daha az olur.

FAQ

Özellik talebi oyları hepsi tek bir hesaptan veya ekipten geliyorsa hiç indirime tabi tutulmalı mı? Evet, ham oy sayısı yerine farklı hesaplara veya organizasyonlara göre ağırlıklandırın, çünkü aynı şirketteki beş kişiden gelen beş oy, bir müşterinin önceliklerini temsil eder, beş bağımsız talep onayını değil.

Biletlerde çokça görünen ama neredeyse hiç oyu olmayan bir özelliği inşa etmeye değer mi? Genellikle evet, bilet hacmi gerçekten farklı hesaplardan geliyorsa ve altta yatan ihtiyaç varsayılmak yerine doğrulanmışsa; düşük oy sayısını panonun aktivasyon maliyetinin bir ölçüm artefaktı olarak ele alın, talebin gerçek olmadığının kanıtı olarak değil.

Bir arayüz kafa karışıklığı biletini bir bakışta gerçek bir eksik özellik biletinden nasıl ayırt edersiniz? Çözümün mevcut bir yeteneği açıklamak mı yoksa eksik biri için özür dilemek mi olduğuna bakın. "Aa, aslında tam orada" çözümlerinin bir deseni bir arayüz veya keşfedilebilirlik sorununa işaret eder; "bunu henüz desteklemiyoruz" deseni gerçek bir boşluğa işaret eder.

Bu ayrım çok küçük bir destek hacminde de aynı derecede önemli mi? Mekanik olarak daha az, çünkü bir avuç bilet toplu analiz gerektirmeden tek tek okunması kolaydır, ama altta yatan önyargı, biletlerin öfkeli kullanıcıları fazla temsil edip sabırlı olanları az temsil etmesi, her ölçekte mevcuttur ve her bileti kendiniz okurken bile akılda tutmaya değer.

Git etiketleri, sürümler ve changelog'unuz

Mon, 07 Sep 2026 00:00:00 GMT

Bir git etiketi, bir sürüm ve bir changelog girişi aynı olayın üç farklı kaydıdır, ve bunları karıştırmak bir changelog'un gerçekte gönderilenden sessizce uzaklaşmasına yol açar. Bir etiket bir commit'i işaretler. Bir sürüm o etiketi artifactlarla ve bir açıklamayla paketler. Bir changelog girişi, deponun dışındaki bir okuyucunun kullanabileceği terimlerle neyin değiştiğini açıklar. Genellikle zaman içinde birbirine yakın gerçekleşirler, ve tam da bu yüzden onları üç adım yerine tek bir adım gibi ele almak kolaydır, ve tam da bu yüzden boşluk ancak aylar sonra, biri "v2.4'te ne gönderildi" diye sorduğunda ve dürüst yanıt gerçek bir kazı gerektirdiğinde görünür hale gelir.

Üçü arasındaki gerçek fark nedir?

Kayıt	Nerede yaşar	Kimin için yazılır
Git etiketi	Depoda, bir referans olarak	Tam olarak o commit'i checkout eden herkes
Sürüm	Kod barındırıcısında (GitHub, GitLab)	Bir build indiren herkes
Changelog girişi	Ürünün kendi changelog'unda	Sadece depoyu değil, ürünü kullanan herkes

Bir etiket üçünün en mekanik olanıdır: git tag v2.4.0 ve tamamdır, içinde ne olduğunu bir şeyin açıklaması gerekmez. Bir sürüm bir açıklama ve genellikle indirilebilir artifactlar ekler, ve kitlesi hâlâ bir sürüm sayfasının ne olduğunu bilen geliştiricilerdir. Bir changelog girişi üçünden depoyu hiç açmayabilecek bir okuyucu için yazılan tek olanıdır, bu yüzden en çok editoryal dikkat gerektiren ve zaman baskısı altında en çok atlanan odur.

Her git etiketi bir changelog girişi gerektirir mi?

Hayır, ve ikisini bire bir ele almak yaygın bir hatadır. Bir etiket dahili bir kilometre taşını, bir release candidate'ı, veya çoğu kullanıcıya hiç ulaşmayan bir hotfix'i işaretleyebilir; bunların hiçbiri zorunlu olarak herkese açık bir giriş gerektirmez. Test, bir şeyin bir changelog'a girip girmeyeceğine karar veren aynı testtir: bir kullanıcı veya çağıran bunu fark eder mi veya önemser mi. Çoğu etiket bu testi geçer. Bazıları, sadece bir CI pipeline'ını tetiklemek için oluşturulan bir etiket gibi, hiç geçmez.

Her changelog girişi kendi etiketini gerektirir mi?

Her zaman değil, ve burada sürekli deploy eden ekipler ile versiyonlanmış paketler gönderen ekipler ayrılır. Günde birkaç kez deploy eden bir SaaS ürünü, deploy başına 1:1 etiket olmadan birden fazla deploy'u tarihli bir changelog girişi altında gruplandırabilir; bir paket kayıt defterinde yayınlanan bir kütüphane genellikle yayınlanan versiyon başına bir etikete ihtiyaç duyar. Go modules ve Swift Package Manager versiyonları doğrudan etiketlerden çözer; npm veya PyPI'da yayınlanan versiyonu kayıt defteri tutar, ve etiket herkesin o versiyonu kaynağına geri eşlemesini sağlar. Bağımsız olarak versiyonlanan birden fazla pakete sahip bir repository, buna tüm repo için bir kez değil, paket bazında karar vermelidir; monorepo changelog'ları etiket öneklerinin ve changelog kapsamının klasör sınırlarına değil paket sınırlarına göre nasıl bölünmesi gerektiğini ele alır. Semantic versioning ve changelog'unuz versiyon numarasının kendisinin changelog kategorilerine nasıl eşlenmesi gerektiğini ele alır; etiketler bir versiyon numarasını gerçek koda karşı doğrulanabilir kılan mekanizmadır.

Bir sürüm açıklaması changelog girişiyle nasıl ilişkilenmeli?

Aynı metin olabilirler, ama sadece ikisinin kitlesi gerçekten aynıysa, ki bu göründüğünden daha nadirdir. Bir kod barındırıcısındaki bir sürüm sayfası neredeyse yalnızca geliştiriciler tarafından okunur; bir üründe changelog'u okuyan teknik olmayan kullanıcılar da varsa, sürüm açıklamasını kelimesi kelimesine kopyalamak, sade dil versiyonuna ihtiyaç duyan bir okuyucuya dahili terimler ve koda odaklı bir ifade gönderir. En temiz desen: changelog girişini birincil, okuyucuya yönelik artifact olarak yazmak, ve sürüm açıklamasının ya ona bağlanmasına ya da orada zaten rahat olan kitle için daha kısa, daha teknik bir özet tutmasına izin vermek.

# Sürüm v2.4.0 (GitHub, geliştiriciler için)
Raporlar pipeline'ını yeni agregasyon motoruna yükseltir. Müşteriye
yönelik özet için changelog'a bakın:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, müşteriye yönelik)
### Added
- Raporlar artık bir milyondan fazla satırı olan hesaplar için bile
  bir saniyeden kısa sürede yükleniyor.

Aynı sürüm, iki belge, her biri kendi okuyucusu için kendi ifadesiyle.

Changelog girişi gerçekte nereden gelir?

İki başlangıç noktasından, ve çoğu gerçek pipeline ikisinin bir karışımıdır. Etiket anında commit mesajlarından üretilebilir, ki bu hızlıdır ve birleştirilmiş bir pull request'i asla kaçırmaz; conventional commits'ten changelog'a o pipeline'ı baştan sona ele alır. Veya etiketten tamamen ayrı olarak, kodun birleştirildiği an yerine bir özelliğin tamamlanmış sayıldığı ana göre zamanlanarak elle yazılabilir. Üretilen girişler tutarlıdır ama her belirsiz commit mesajını devralır; elle yazılan girişler daha nettir ama onları gerçekten yazacak birine ihtiyaç duyar. Otomasyon kullanan çoğu ekip, ham metin nereden gelmiş olursa olsun, Keep a Changelog, uygulamada'nın önerdiği aynı disiplinle, üretilen metin herkese açık giriş olmadan önce yine de hafif bir düzenleme geçişi tutar.

Üçü senkronizasyondan çıktığında ne bozulur?

Okuyucunun önce kontrol ettiği şeye olan güven. Karşılık gelen bir changelog girişi olmadan var olan bir etiket, changelog okuyucusunun tarafından bakıldığında, o hafta hiçbir şey olmamış gibi görünür. Karşılık gelen bir etiket veya sürüm olmadan bir changelog girişi, üretimde bir sorunu debug eden birinin bir giriş yayınlandığında canlı olan tam kodu checkout etmesini imkansız kılar. Çözüm mükemmel otomasyon değil, eşleme için tek bir gerçek kaynağıdır: sürüm sürecinin kendi kontrol listesi olsa bile, gönderilebilir bir değişikliğin onu tanıtan aynı commit veya pull request'te üçünü de aldığını söyleyen bir yer.

FAQ

Changelog girişleri git etiketlerinden otomatik olarak üretilmeli mi? Bir başlangıç noktası olabilirler, ama tek başına bir etiket okuyucuya yönelik hiçbir açıklama taşımaz, sadece bir commit aralığı. Otomatik üretim, kullanılabilir bir şey üretmek için sadece etiketin varlığını değil, o aralıktaki commit mesajlarını okumak zorundadır.

Her sürümü etiketlemezsek ne olur? O zaman changelog girişi birincil kayıt haline gelir, ve yine de bir tarih ve, ürünün bir tanesi varsa, bir versiyon numarası taşımalıdır, böylece giriş karşılık gelen bir etiket olmadan bile sonradan bir okuyucunun başvurabileceği bir şey olarak kalır.

Ön sürüm etiketleri (v2.4.0-rc.1 gibi) changelog girişlerine sahip olmalı mı? Genellikle hayır. Bir release candidate dahili veya beta testi içindir, ve onun için bir changelog girişi okuyucuları hiç açıklandığı gibi gönderilmeyebilecek versiyonlar için giriş beklemeye alıştırır. Girişleri genel kullanılabilirliğe ulaşan etiketlere ayırın.

Tek bir changelog girişi birden fazla git etiketini kapsayabilir mi? Evet, ve sık sık etiketleyen ekipler için genellikle öyle olmalıdır. İlgili etiketleri, bir özelliği birden fazla okuma boyunca parçalayan etiket başına ince bir giriş yayınlamak yerine, net değişikliği açıklayan tarihli bir giriş altında gruplandırın.

Dahili API changelog'ları: diğer ekip için ne değişir

Mon, 07 Sep 2026 00:00:00 GMT

Bu hub'daki diğer her yazı bir API'yi çağıranın şirket dışında olduğunu varsayıyor: bir müşterinin mühendisi, bir ortak, dokümanları kendi başına bulan biri. Birçok API'nin tamamen farklı bir çağıranı var, koridorun karşısındaki veya iki kat öteki bir ekip, ve bu bir changelog'un ona ne borçlu olduğu hesabını değiştiriyor, çünkü bir Slack mesajı ona ulaşır ve genelde hiç destek talebi açılmaz. Çoğu ekip bundan dahili API'lerin changelog'a ihtiyacı olmadığı sonucunu çıkarıyor. Gerçekten ihtiyaç duydukları şey farklı bir changelog.

Dahili bir API'nin changelog'unu genel olandan farklı yapan nedir?

Genel bir API changelog'unun örtük bir kitlesi vardır: o API'nin oluşturduğu tek şeyi kullanan herkes. Dahili bir API'nin kitlesi doğrudan ulaşılabilir, ki bu çoğu genel API changelog'unun var olma nedeninin çoğunu ortadan kaldırır: tek tek iletişime geçilemeyen çağıranlara yayın yapmak. Dahili bir API'ye sahip ekip genelde hangi başka ekiplerin onu çağırdığını, bazen belirli servis seviyesine kadar, tam olarak bilir. Bu, genel bir feed'i değil, hedeflenmiş bir mesajı doğal varsayılan yapar, ve dahili API'lerin çoğu kez hiç changelog'suz kalmasının nedeni de budur: sahip ekip hatırladığı iki üç ekibi bilgilendirir, bunun herkesi kapsadığını varsayarak.

	Genel API changelog'u	Dahili API changelog'u
Kim okur	Herhangi bir dış çağıran, genelde doğrudan ulaşılamaz	Küçük, genelde bilinen bir dahili ekip kümesi
Varsayılan kanal	Bir sayfa ve bir feed	Çağıran ekiplere bir mesaj, ideal olarak bir sayfa da
En büyük risk	Bir çağıran girişi tamamen kaçırır	Sahip ekip varlığını hatırlamadığı bir çağıranı unutur
"Bizi kimin çağırdığını bilmiyoruz"un yerini ne alır	Hiçbir şey; geniş yayınla	Güncel tutulan gerçek bir çağıran kaydı

"Bizi çağıran ekiplere haber veririz" neden çöker?

Çünkü çağıranların kümesi hiçbir zaman sahip ekibin hatırladığı kadar küçük veya durağan değildir. Tek bir tüketici için inşa edilen bir servis altı ay sonra hiç duyurulmamış bir entegrasyon üzerinden ikinci bir çağıran kazanır, ve sahip ekibin zihnindeki "bizi kim çağırıyor" listesi kimse fark etmeden yanlış hale gelir. Bu başarısızlık sıradan ve yaygındır, bir kayıt yerine hafızaya güvenmenin varsayılan sonucudur, kimsenin dikkatsiz olduğunun işareti değil. Breaking change nedir bir API değişikliğinin öncelikle breaking sayılıp sayılmayacağına nasıl karar verileceğini ele alır; dahili durum bunun üzerine ikinci, daha zor bir soru ekler: kimin bilgilendirileceğini bilmek.

Dahili bir API'nin genel tarzda bir changelog sayfasına ihtiyacı var mı?

Genelde evet, birincil kanal doğrudan olsa bile. Bir sayfa doğrudan mesaja bağlanacak bir şey verir, böylece bildirim kısa kalabilir ("/v2/accounts'ta breaking change, detaylar burada") kaydırılıp gidecek bir sohbet mesajında tüm açıklamayı taşımaya çalışmak yerine. Ayrıca yeni bir ekibin, ya da doğrudan mesajı kaçıran bir ekibin, entegrasyonu bozulduğunda ve nedenini anlamaya çalışırken kontrol edebileceği şey haline gelir. Sayfanın cilalı veya herkese açık olması gerekmez; bağlanabilir olması ve onu duyuran Slack thread'inden daha uzun yaşaması gerekir.

Çağıranların listesini gerçekte kim tutar?

Sahip ekip, ve bu kabile bilgisi değil gerçek bir yapı taşı olarak ele alınmalıdır. En ucuz versiyon, API'nin kendi deposundaki bir dosya, her yeni entegrasyon inşa edildiğinde güncellenen, her girişte bir sorumlusu olan kısa bir tüketici servisler listesidir, herhangi bir bağımlılık bildirimiyle aynı disiplin. Alternatif olan her breaking change öncesi soruşturmak, birinin doğru kişiye sormayı unuttuğu o bir sefere kadar işe yarar, ve sessizce bozulan dahili bir API bir ekip için genel bir API'ninkinden daha küçük bir olaydır, ama yine de bir olaydır, genelde API'nin sahibi tarafından değil o ekibin kendi nöbetçisi tarafından keşfedilir.

# consumers.yml
- service: billing-service
  owner: "#team-billing"
  since: 2026-03-01
- service: reporting-pipeline
  owner: "#team-analytics"
  since: 2026-06-14

Böyle bir dosya "kimi bilgilendirmemiz gerekiyor"u bir sorudan bir sorguya dönüştürür. Tam olarak bu sorun için inşa edilmiş araçlar, Backstage'in servis kataloğu gibi, API'leri tanımlanmış tüketicileri olan birinci sınıf varlıklar olarak modeller, aynı nedenle: bir kuruluşun yeterince dahili servisi olduğunda, kimin neyi çağırdığına dair kimsenin hafızası kendi başına doğru kalmaz, ve bir şeyin bu kaydı tutması gerekir. Zaten dahili olarak çalıştırdığınız aracın dokümanları, özel bir tane inşa etmeden önce bakılacak doğru yer genelde budur.

Genel bir changelog'un ihtiyaç duymayacağı, dahili bir girişte ne olmalı?

Daha fazla operasyonel somutluk, çünkü okuyucu aynı altyapı içinde buna göre hareket edecek başka bir mühendistir, bunu bir özet olarak okumayacaktır. Değişikliğin hangi ortamlarda ne zaman canlı olduğu, çünkü dahili servisler genel bir çağıranın hiç görmediği aşamalardan terfi eder. Değişiklik tüketici tarafında bir yapılandırma ya da istemci kütüphanesi güncellemesi gerektiriyor mu, varsa bir komut olarak ifade edilmiş şekilde. Ve, dahili çağıranlar düzeltmeyi genelde doğrudan sahip ekiple koordine edebildiği için, bir destek kanalı yerine isimle belirtilmiş bir kişi: "bir şeyi bozarsa @maria'ya haber ver" dahili bir girişte tamamen makul bir satırdır ve genel bir API changelog'unda tuhaf bir satırdır.

Bu, bir monorepo içindeki bir changelog için de aynı şekilde geçerli mi?

Sorunu değiştirmek yerine keskinleştirir. Monorepo changelog'ları bir paketin ne zaman kendi changelog'una ihtiyaç duyduğunu ele alır; bir monorepo'da birkaç paketten biri olan dahili bir API'nin tüketicilerinin yine de açıkça izlenmesi gerekir, çünkü çağıranlarıyla aynı depoyu paylaşmak, bir şey onlara bakmalarını söylemedikçe bir değişikliği fark edecekleri anlamına gelmez. Repo'daki yakınlık, dikkatteki yakınlıkla aynı şey değildir.

FAQ

Yalnızca dahili bir API'nin tek bir çağıranı varsa changelog'a ihtiyacı var mı? Neredeyse hiç, ve o tek ekibe doğrudan bir mesaj genelde yeterlidir. Birden fazla çağıran olduğunda, veya çağıran listesi sahip ekibi bir kez şaşırttığında changelog kendini kanıtlar, çünkü bu hafızanın tek başına artık güvenilir olmadığının işaretidir.

Dahili API değişiklikleri genel olanlarla aynı incelemeden mi geçmeli? Okuyucu dış bir çağıran değil bir meslektaş olduğu için ifade daha hafif olabilir, ama bir değişikliğin breaking olup olmadığı kararı her iki durumda da aynı özeni hak eder. Dahili bir çağıranın yine de eski davranışa bağımlı üretim kodu vardır.

Hiç izlenmediyse dahili bir API'yi kimin çağırdığı nasıl öğrenilir? Sunucu logları ya da bir service mesh'in trafik verisi, hiç tüketici kaydı tutulmadıysa dürüst cevaptır; bu keşfi bir tanesini başlatma anı olarak ele al, tek seferlik bir temizlik olarak değil.

Bir Slack mesajı yeterli mi, yoksa dahili bir değişiklik yine de resmi bir changelog girişine mi ihtiyaç duyar? Saf olarak eklemeli olmayan her şey için ikisi de. Mesaj zamanında okunan şeydir; giriş, haftalar sonra bir sorunu araştıran ve mesajı hiç görmemiş bir ekibin yine de bulabileceği şeydir.

Dahili release notları: kimin bilmesi gerekir

Mon, 07 Sep 2026 00:00:00 GMT

Bu hub'daki diğer her yazı, bir release notunu okuyanın bir müşteri olduğunu varsayar. Destek, satış ve customer success de okur, veya okumaya çalışır, ve çoğu neyin gönderildiğini önce bir müşteri sorduğu için öğrenir. Bu sıra tersine dönmüştür, ve çoğu şirkette de varsayılan budur, çünkü release süreci müşteriye yönelik not çıktığı anda biter, ve kimse bir saat sonra bu konuda soru yanıtlaması gereken insanlar için ikinci, daha küçük bir adım kurmamıştır.

Dahili bir release notu nedir, ve müşteriye yönelik olandan nasıl farklıdır?

Ürünü zaten derinlemesine bilen insanlar için yazılmış, onlara neyin değiştiğini ve kendi somut işlerinde ne yapmaları gerektiğini söyleyen daha kısa bir belgedir. Bir destek temsilcisi, müşteriye yönelik bir duyurunun kullandığı cilalı çerçeveye ihtiyaç duymaz; değişikliğin ürün içinde şu anda nasıl göründüğünü, hakkında en olası sorunun ne olacağını, ve açık biletlerin etkilenip etkilenmediğini bilmesi gerekir. Müşteriye yönelik bir not değişikliği satar. Dahili bir not birini bununla başa çıkması için donatır.

Okuyucu kitlesi	Bilmesi gereken	Nerede ihtiyaç duyar
Destek	Arayüzde ne değişti, olası sorular, etkilenen açık biletler	Zaten cevap aradığı yerde
Satış	Bir anlaşma için neyi açtığı, henüz neyi yapmadığı	Görüşmelere hazırlandığı yerde
Customer success	Mevcut müşterilere ne söylenmeli, ve kim istedi	Erişimi planladığı yerde
Üst yönetim	Söz verilene karşı ne gönderildi, ve ne zaman	Release başına değil, kısa ve tekrarlayan bir özet

Dahili ekipler lansmanları neden geç öğrenir?

Çünkü release süreci genellikle tek bir eserin, müşteriye yönelik notun veya changelog girişinin etrafında kurulur, ve dahili olan her şeyin bu tek belgeyi okumaktan çıkarılacağı varsayılır. Öyle değildir. Destek temsilcileri önlerindeki biletle meşguldür, bağlam için bir changelog'a göz atmıyorlardır, ve bir müşteri için yazılmış bir not, sık sık bir temsilcinin ihtiyaç duyduğu tam olarak o operasyonel ayrıntıyı, örneğin özelliğin hangi plana kilitli olduğunu veya başarısız olduğunda hata mesajının neye benzediğini atlar. Bir müşteri sorduğunda, temsilci müşterinin az önce okuduğu aynı genel notu, hiçbir avantaj olmadan okuyordur.

Dahili bir release notu, müşteriye yönelik olanın söylemediği neyi söylemeli?

Müşteriye yönelik bir notun bilerek dışarıda bıraktığı operasyonel ayrıntılar. Hangi planların veya hesapların bunu aldığı. Bir şey ters gittiğinde nasıl göründüğü, ve buna denk gelen bir müşteriye ne söyleneceği. İlgili bir biletle çalışan bir temsilcinin kontrol etmesi gerektiğini bilmesi için, açık bir talep veya bileti kapatıp kapatmadığı, ve hangisini. Bir soru notun kapsadığından öteye giderse ekipte kimin sorumlu olduğu. Bunların hiçbiri, şirket dışından birinin bir kez okuması için yazılmış müşteriye yönelik sürüme ait değildir; tüm bunlar, aynı soruyu haftada kırk kez yanıtlayan birinin gerçekten ihtiyaç duyduğu şeydir.

Dahili not: toplu CSV export (08.09.2026 çıkıyor)

- Sadece Team ve Enterprise planlarına kilitli. Free ve Pro'da
  değişiklik yok.
- Yaygın hata: 50 bin satırın üzerindeki export'lar zaman
  aşımına uğrar; bilinen sorun, düzeltme ayrı takip ediliyor.
  Müşteriye tarih aralığına göre filtrelemesini söyle.
- `bulk-export` etiketli 14 açık talebi kapatır. Paylaşılan
  belgede yanıt şablonu var.
- Sorumlu: platform ekibi, bu notun ötesindeki her şey için
  #platform-eng.

Bir destek temsilcisinin hemen kullanabileceği dört satır, hiçbiri aynı özellik için genel changelog girişine ait olmayacak.

Bunu kim yazmalı, ve ne zaman?

Müşteriye yönelik notu yazan kişi genelde doğru kişidir, çünkü zaten tüm bağlama sahiptir, ama tek bir belgenin her iki okuyucu kitlesine hizmet etmeye çalışması yerine ayrı, kısa bir geçiş olmalıdır. Onları birleştirmek ya dahili ayrıntılarla dolu müşteriye yönelik bir not, ya da gerçekten yararlı olmak için fazla cilalı dahili bir not üretir, ve pratikte iki kısa belge yazmak, tek bir belgeyi aynı anda iki okuyucu kitlesine hizmet ettirmek için pazarlık etmekten daha hızlıdır. Zamanlama yazarlıktan daha önemlidir: dahili not, destek bir değişikliği bir müşteriyle aynı yerden asla öğrenmesin diye, sadece birkaç saat bile olsa müşteriye yönelik olandan önce çıkmalıdır.

Destek'in bir bilet anında gerçekten bulması için nerede yaşamalı?

Bir bilet geldiğinde ekibin zaten baktığı yerde, kimsenin kendiliğinden açması için nedeni olmayan ayrı bir changelog'ta değil. Paylaşılan bir bilgi tabanı kullanan bir destek ekibi, notun orada, ürünün o bölümüyle ilgili biletlerin zaten etiketlendiği yerden bağlantılı olmasına ihtiyaç duyar. Paylaşılan bir kanalda yaşayan bir ekip, onun orada, aranabilir, ilgili olduğu anda yayınlanmasına ihtiyaç duyar, bir kez göz attıkları günlük bir özete gömülü olması yerine. Hedeflenmiş bildirim ile özet yazısındaki müşteriye yönelik kalıp burada da geçerlidir: belirli, yaklaşan bir değişiklik hakkındaki dahili bir not, ilk bilet zaten var olduktan sonra gelen haftalık bir özeti beklemek yerine ekibe doğrudan ulaşmalıdır.

Dış olanla aynı inceleme titizliğine ihtiyacı var mı?

Daha azına, ve bu bilinçli bir tercihtir. Müşteriye yönelik bir not şirketi kamuya açık olarak temsil eder ve dikkatli bir düzenleme geçişini hak eder; dahili bir not hızlı ve somut olmak için vardır, ve onu aynı cila standardına tutmak genellikle tam olarak ekiplerin onu hiç yazmamasına yol açan şeydir. Lansmandan bir saat önce çıkan hızlı, biraz kaba dahili bir not, ilk destek bileti zaten kafası karışık geldikten sonra ertesi gün gelen cilalı bir nottan daha iyidir.

FAQ

Dahili release notları müşteriye yönelik olanlarla aynı onay sürecinden mi geçmeli? Hayır. Daha hafif, daha hızlı bir geçiş tam olarak amaçtır. Aynı incelemeyi zorunlu kılmak, aynı gün çıkacak dahili bir notu, destek onsuz soruyu çoktan yanıtladığında çıkacak bir sonraki hafta notuna dönüştürür.

Dahili iletişim için ayrı bir rol yoksa dahili release notlarından kim sorumlu olmalı? Müşteriye yönelik notu yazan kişi, hemen ardından gelen ikinci, kısa bir geçiş olarak. Ayrı bir sorumlu kişiye ihtiyaç yoktur, sadece müşteriye yönelik notu bir release'in ürettiği tek eser gibi ele almama alışkanlığına.

Dahili release notlarının kendi changelog'una veya arşivine ihtiyacı var mı? Aranabilir bir yer, kimsenin kaydırmadığı kronolojik bir arşivden daha iyidir. Destek zaten bir bilgi tabanına sahipse, not, sadece gönderildiği tarihi zaten bilen birine yardımcı olan ayrı bir dahili changelog yerine, özelliğe etiketlenmiş olarak orada olmalıdır.

Küçük değişikliklerde dahili release notlarını atlamanın riski nedir? Küçük değişiklikler tam olarak destek'in önceden haber verilmeden soru aldığı değişikliklerdir, çünkü küçük bir değişiklik nadiren şirket çapında bir duyuru alır. Release notunun boyutu değişikliğin boyutuyla ölçeklenmeli; değişiklik küçük olduğu için asla sıfıra düşmemeli.

Mobil uygulamalar için release notes: sınır neyi keser

Mon, 07 Sep 2026 00:00:00 GMT

Bu hub'da release notes yazmakla ilgili her şey tamamen kontrol ettiğin bir sayfayı varsayıyor: istediğin uzunluk, çalışan linkler, render edilen biçimlendirme. Mobil bir uygulamanın release notes'u başka birinin kutusunda yaşar. Apple yaklaşık 4.000 karakter verir ama "devamı"na dokunulmadan önce sadece ilk birkaç satırı gösterir; Google benzer bir alan verir, aynı etkili önizleme sorunuyla, ve her iki platform da metin içinde tıklanabilir bir link render etmez. Gerçekten okunan release notes nasıl yazılır yazısındaki kurallar hâlâ geçerli: neyin değiştiğini ve okuyucunun ne yapması gerektiğini söylemek, ama bunu yapacak alan bir changelog sayfasının izin verdiğinin küçük bir kısmıdır, ve kesintiler yanlışlıkla değil bilinçli yapılmalıdır.

Görünür önizlemeye gerçekte ne sığar?

Cihaza ve yazı tipi boyutuna bağlı olarak yaklaşık 80 ila 170 karakter olan ilk bir veya iki satır, okuyucunun genişletmek için dokunması gerekmeden önce. Bu, release note'un geri kalanını kimsenin okuyup okumayacağına karar veren kısmının tüm bütçesidir, ve bu, en önemli cümlenin ilk gelmesi gerektiği anlamına gelir, versiyon numarası değil, bir selamlama değil, bir kategori başlığı değil. "Bu sürümdeki yenilikler:" ile başlayan bir release note, okuyucuya hiçbir şey söylemeyen dört kelimeye görünür alanının üçte birini şimdiden harcamıştır.

Platform	Yaklaşık toplam sınır	"Devamı"ndan önceki etkili önizleme
App Store (iOS)	~4.000 karakter	2-3 satır, yaklaşık 80-170 karakter
Google Play	Dil başına ~500 karakter, bazı alanlar daha kısa	2-3 satır, iOS'a benzer
İkisi de	Release notes alanında tıklanabilir link yok	Yok

"Şimdi ne yapabilirsin, ne borçlusun" kuralı bu uzunlukta hâlâ işe yarıyor mu?

Evet, ve daha katı hale gelir, farklı değil. Girdi başına bir cümle, önce fiil, giriş yok: "Verilerini Ayarlar'dan CSV olarak dışa aktar." "Kullanıcıların artık verilerini CSV formatında dışa aktarabilmesi özelliğini ekledik" cümlesini kelimelerin üçte birini kullanarak aynı şeyi söyleyerek yener. Changelog sayfası uzunluğunda, biraz gevezelik eden bir cümle okuyucuya yarım saniyeye mal olur. Mobil release note uzunluğunda, aynı geveze anlatım cümleyi tamamen görünür önizlemenin dışına itebilir, böylece okuyucu neyin değiştiğini söyleyecek fiili hiç görmez.

Kötü, önizlemeyi çerçeveye harcıyor:
"İyileştirmelerle dolu yeni bir güncelleme sunmaktan
heyecan duyuyoruz! Detaylar için okumaya devam edin."

İyi, tüm değer ilk satırda:
"Verilerini CSV olarak dışa aktar. Karanlık mod artık
sistem ayarına uyuyor. Paylaşılan linkleri açarken
oluşan çökme düzeltildi."

Bir web changelog girişinin normalde tutacağı ne kesilmeli?

Önce linkler, çünkü iki mağazadan hiçbiri onları tıklanabilir hale getirmiyor, bu yüzden metindeki bir URL okuyucunun yeniden yazması gereken ölü ağırlıktır. Girişin bir hedefe ihtiyacı varsa, bunun yerine uygulamada nereye dokunulacağını söyle: "Yeni filtreleri Ayarlar > Arama altında gör" işe yarar; "example.com/blog/filtreler adresinde devamını oku" bu yüzeyde işe yaramaz. İkincisi, koşullu veya belirli bir kitleye özgü her şey: bir web changelog'u "API kullanıyorsan, bu seni etkiler" diyebilir, ama bir mağaza girdisi her kurulu kullanıcıya aynı anda ulaşır, bu yüzden koşullu bir satır bunun uygulanmadığı %95 için gürültü gibi okunur. Koşullu detayı bunun yerine gerçekten ilgilendirdiği hesaplar için tetiklenen bir uygulama içi mesaja koy.

Her sürümün kendi notları mı olmalı, yoksa "hata düzeltmeleri ve performans iyileştirmeleri"ni yeniden kullanmak sorun değil mi?

Bunu gerçekten öyle olan sürümler için yeniden kullan, ama bunun ne sıklıkla gerçekten doğru olduğunu denetle. Release notes nasıl yazılır bu ifadenin neden okuyucu için değil içeriden yazılmış bir notu ele verdiğini zaten ele alıyor; mobilde çift zarar veriyor, çünkü mağaza release notes'u bazı kullanıcıların güncellemeler arasında bir şey gördüğü nadir yerlerden biridir, ve uzun bir "hata düzeltmeleri ve performans iyileştirmeleri" dizisi uygulamanın değişmediği gibi okunur, ki bu o dönem için hiç not olmamasından daha kötü bir izlenimdir.

Release notes insanların uygulamayı güncelleyip güncellemeyeceğini etkiler mi?

Dolaylı olarak, ikna yerine görünürlük yoluyla. Çoğu kullanıcı otomatik olarak günceller ve güncellemeden önce notları hiç okumaz; notlar en çok güncellemeleri elle kontrol eden azınlık için, ve bir mağaza girdisinin geçmişini tarayan eleştirmenler veya basın için önemlidir. O daha küçük kitle için yazmak yine de karşılığını verir, çünkü belirli, tarihli girişlerin gerçek bir geçmişine sahip bir girdi aktif olarak sürdürülen bir uygulama gibi okunur, ve bir yıl boyunca "hata düzeltmeleri ve performans iyileştirmeleri" olan bir girdi okunmaz, o sürede gerçekte ne kadar şey yayınlanmış olursa olsun.

Ya kullanıcının seçeneği olmadığını notun açıklaması gereken zorunlu bir güncelleme?

Nedeni ve son tarihi her şeyden önce ilk satırda belirt, çünkü zorunlu güncelleme okuyucunun okumaya başlamadan önce bile rahatsız olduğu tek durumdur. "Bu güncelleme verilerinin senkronize olmaya devam etmesi için gerekli. Kesintiyi önlemek için [tarih]'e kadar güncelle." tek cümlede ne yapılacağını ve nedenini söyler; bu nedeni üç satır ilgisiz özellik notunun altına gömmek, uygulamanın rahatsız edici kısmı sakladığı gibi okunur.

FAQ

Mobil release notes aynı sürümün web changelog'uyla eşleşmeli mi? Aynı temel değişiklikleri kapsamalı, ama kelimesi kelimesine değil. Web changelog'u tam açıklamayı karşılayabilir; mobil not aynı gerçekleri önce fiil olacak şekilde bir cümleye sıkıştırılmış olarak ister, ki bu genelde kopyala-yapıştır değil yeniden yazım olduğu anlamına gelir.

Desteklenen her dil için mobil release notes'u yerelleştirmeye değer mi? Evet, bir web changelog'undan daha fazla, çünkü mağaza girdisi bazı kullanıcıların oturumlar arasında gördüğü tek yerelleştirilmiş yüzey olabilir, ve her iki platform da çeviri dışında ek mühendislik işi olmadan yerel başına release notes'u destekler.

Kısalığı zorlayan bir sınır yoksa mobil bir release note ne kadar uzun olmalı? Yine de kısa. iOS'taki 4.000 karakter tavanı nadiren gerçek kısıtlamadır; gerçek kısıtlama 2-3 satırlık önizlemedir, ve o önizlemenin gösterdiğinin ötesine yazmak sadece daha az insanın önemli olan kısmı okuduğu anlamına gelir.

Release notes'un görünür metinde bir versiyon numarasına ihtiyacı var mı? Hayır. Mağaza notların yanında versiyon numarasını zaten gösterir. Onu metin içinde tekrarlamak okuyucunun zaten önünde olan bilgi için görünür karakter harcar.

Monorepo changelog'ları: tek mi, paket başına mı?

Mon, 07 Sep 2026 00:00:00 GMT

Bir monorepo, tek bir repository içinde ayrı ayrı deploy edilen birkaç şeyi barındırır, ve bir changelog önce bir soruyu yanıtlamalıdır: okuyucu repo'yu mu önemsiyor, yoksa içindeki belirli bir paketi mi? Çoğu ekip buna hiç bilinçli olarak karar vermez. Tek bir repo olduğu için tek bir changelog'la başlarlar, zaman içinde paket ekler, ve CLI kullanan birinin kendi düzeltmesini gönderen girişi bulmak için kırk ilgisiz backend girişini geçmesi gereken bir log ile sonuçlanırlar. Doğru şekli belirleyen repository'nin yapısı değil, log'u kimin okuduğu ve zaten neyi aradığını bilmesidir.

Bir monorepo'nun changelog'unu tek bir repo'dan farklı kılan nedir?

Tek repo changelog'unun örtük bir okuyucu kitlesi vardır: o repo'nun inşa ettiği tek şeyi kullanan herkes. Bir monorepo'nun okuyucu kitlesi paket bazında bölünür, ve aynı repo'daki paketler sık sık farklı takvimlerde, farklı tüketicilere, farklı kararlılık seviyelerinde yayınlanır. Bir kayıt defterinde yayınlanan bir kütüphane ile dahili bir yönetim aracı aynı monorepo'da yaşayabilir ve changelog'u okuyan biri için neredeyse hiçbir ortak noktaları olmayabilir.

Repo şekli	Tipik okuyucu	Uyan changelog
Tek bir deploy edilebilir uygulama	Ürünü kullanan herkes	Tek log, tüm repo için
Kütüphane workspace'i (birden fazla yayınlanan paket)	Belirli bir pakete bağımlı olan	Paket başına bir log
Uygulama artı dahili araçlar	Örtüşmeyen iki farklı okuyucu kitlesi	Klasöre değil, okuyucu kitlesine göre bölünmüş
Uygulama artı kendi SDK'sı	Ürün kullanıcıları, ve SDK entegratörleri	İki log: ürüne özel, SDK'ya özel

Her paketin kendi changelog'una ihtiyacı var mı?

Sadece bağımsız bir okuyucu kitlesi olanların. Bir kayıt defterinde yayınlanan bir paket kendi log'una ihtiyaç duyar, çünkü onu kuran kişinin repo'da başka bir şey okumak için hiçbir nedeni yoktur, ve Lerna ve Changesets gibi monorepo sürüm araçları her paket için package.json'ının yanına bir CHANGELOG.md yazar. Aynı repo'da zaten yaşayan uygulamayı tek tüketicisi olan dahili bir yardımcı programın ayrı bir log'a ihtiyacı yoktur; değişikliklerini o uygulamanın girişlerine dahil etmek, ekip dışında kimsenin açmadığı ikinci bir dosyadan daha kullanışlıdır.

Test, herhangi bir girişin bir changelog'a ait olup olmadığına karar verenle aynıdır: okuyucu bunu fark eder mi veya önemser mi, ve bunu bilerek harekete geçebilir mi. Bunu klasöre değil pakete göre uygula, ve on iki paketli bir repo, iki gerçek changelog'la ve buna hiç ihtiyacı olmayan on paketle sonuçlanabilir.

Hangi paketin hangi changelog girişine neden olduğu nasıl bilinir?

Her girişi, bir commit'in hangi dosyaları etkilediğini sonradan inceleyerek değil, giriş yazıldığı anda paketiyle etiketle. Paylaşılan dahili bir kütüphaneyi düzelten bir commit, ona bağımlı olan her pakette bir changelog girişi üretebilir, ve dosya yolları tek başına bu alt akış girişlerinden hangisinin okuyucunun gerçekten görmesi gerektiğini söyleyemez; sadece "bu, A paketini kullanana görünür ve B paketini kullanana görünmez" diye karar veren bir kişi bunu yapabilir. Conventional commits her commit'te paketi adlandırarak burada mekanik olarak yardımcı olur, ama scope yine de sadece bir taslak üretir. O yazının aynı iki katmanlı kuralı paket bazında geçerlidir: doğru scope'a sahip bir taslak, o paketin gerçek okuyucusu için ifade edilmeden önce yine de insan eliyle bir geçiş gerektirir.

Paylaşılan bir changelog, tek repo changelog'unun ihtiyaç duymadığı neye ihtiyaç duyar?

Her girişte, açıklamadan önce, en başta bir paket etiketi, böylece log'a göz atan bir okuyucu tek bir geçişte kendisine ait olmayan her şeyi atlayabilir. Bu etiket olmadan, paylaşılan bir log rastgele bir akış gibi okunur, ve bir pakete ilgi duyan bir okuyucu, hangi satırların önemli olduğunu ezberlemek dışında onu filtrelemenin bir yolunu bulamaz, ki bunu ilk haftadan sonra kimse yapmaz.

## 2026-09-07

### [cli] Eklendi
- `acme push --dry-run` gerçekten göndermeden neyin
  gönderileceğini gösterir.

### [core] Düzeltildi
- Yeniden deneme geri çekilmesi artık boş gövde döndüren başarılı
  bir istekte sıfırlanmıyor.

İki giriş, iki okuyucu kitlesi, ayırt etmek için tek bakış. Changesets tarzı bir iş akışı bu etiketlemeyi doğrudan release sürecine gömer: katkıda bulunan biri değişikliğinin yanında pakete özel kısa bir not yazar, ve araç, birleştirilmiş bir commit geçmişinden geriye dönük paket sınırlarını yeniden inşa etmeye çalışmak yerine, release anında bu notlardan paket başına changelog'lar ve versiyon sıçramaları oluşturur.

Versiyonlama bir monorepo changelog'uyla nasıl ilişkilenir?

Bağımsız olarak versiyonlanan paketlerin kendi changelog'una ihtiyacı vardır çünkü kendi versiyon numaraları vardır, ve paylaşılan bir changelog, tek bir dosya içinde iki log'a dönüşmeden "A paketi 2.1'den 2.2'ye geçerken B paketi 1.4'te kaldı" ifadesini veremez. Semantic versioning ve changelog'unuz bir versiyon numarasının changelog kategorilerine nasıl eşlenmesi gerektiğini ele alır; bir monorepo'da bu eşleme paket bazında uygulanmalıdır, çünkü bir pakette bulunan breaking change, ona bağımlı olmayan kardeş bir paket için breaking change değildir.

Bir ürünü, birçok dahili paketten inşa edilmiş olsa bile tek bir deploy edilebilir birim olarak gönderen bir repo bu sorunu yaşamaz: paketler her zaman birlikte release edildikleri için bir versiyonu paylaşırlar, ve tek bir changelog doğrudur.

Git etiketleri bir monorepo'ya nasıl uyar?

Git etiketleri, release'ler ve changelog'unuz yazısındaki aynı kural, paket bazında uygulanarak geçerlidir: kendi versiyonu olan bir paketin kendi etiket önekine ihtiyacı vardır, tipik olarak hangi pakete ait olduğunu söyleyemeyen çıplak bir v1.4.0 yerine paket-adi@1.4.0. Sadece çıplak versiyon numaralarıyla etiketlenmiş bir monorepo, sonradan "cli 2.2'yi gönderdiğinde core'da ne vardı" sorusunu yanıtlayamaz, çünkü diskte hiçbir şey o etiketin gerçekte hangi pakete ait olduğunu kaydetmez.

FAQ

Bir monorepo'daki her paket için ayrı bir changelog'a ihtiyacım var mı? Sadece bağımsız okuyucu kitlesi olan paketler için, genellikle bir kayıt defterinde yayınlanan her şey. Aynı repo'da zaten yaşayan tek bir dahili tüketicisi olan bir paket, kendi log'unu tutmak yerine o tüketicinin log'una dahil olabilir.

Bir changelog girişini doğru paketle ne etiketler? Değişen dosya yollarının otomatik bir taraması değil, girişi yazan kişi, onu yazdığı anda. Paylaşılan bir kütüphanedeki bir değişiklik, ona bağımlı her pakette farklı bir giriş üretebilir, ve sadece bir insan bu alt akış girişlerinin her birinin gerçekte ne söylemesi gerektiğine karar verebilir.

Bir monorepo her şey için tek bir versiyon numarası mı kullanmalı? Sadece her paket her zaman diğerleriyle birlikte release edilirse. Paketler bir gün bağımsız olarak yayınlanırsa, bağımsız versiyonlara ihtiyaç duyarlar, ve bağımsız versiyonların anlamlı olması için bağımsız changelog'lara ihtiyaçları vardır.

Bir monorepo changelog aracı insan düzenleme adımının yerini alır mı? Hayır. Changesets gibi araçlar, release anında pakete özel notları toplama ve birleştirme işini otomatikleştirir; notun kendisi, katkıda bulunanın değil okuyucunun diliyle yazılmış olarak, başka her changelog pipeline'ında olduğu gibi hâlâ bir kişinin işidir.

Yeni bir özellik nasıl duyurulur (sessizlik olmadan)

Mon, 07 Sep 2026 00:00:00 GMT

Çoğu özellik duyurusu, kimsenin iki kez okumadığı bir kanalda ölür: kayıp giden bir tweet, bir abonenin o hafta aldığı diğer on ikisinin altında gömülü kalan bir sürüm günü e-postası, ekibin yarısının aylar önce sessize aldığı bir kanaldaki bir Slack mesajı. Özellik gönderildi. Onu kullanacak olanların neredeyse hiçbiri fark etmedi. Bunu düzeltmek, daha iyi bir duyuru yazmaktan çok, doğru okuyucu için doğru kanalı seçmekle ve genel bir mesajı fark etmelerine güvenmek yerine tam olarak isteyen kişilere doğrudan ulaşmakla ilgilidir.

Yeni bir özellik gerçekte nerede duyurulmalı?

Birden fazla yerde, çünkü "herkes aynı kanalı okur" hiçbir zaman doğru değildir. Bir changelog veya feed girişi, kendi ritminde kontrol eden ve kalıcı, tarihli kaydı isteyen okuyucuya hizmet eder. Uygulama içi bir bildirim, ürünü zaten kullanan ve varlığından haberdar olsa özelliği bugün kullanacak okuyucuya hizmet eder. E-posta, şu anda üründe olmayan ama doğru güncelleme için geri dönecek okuyucuya hizmet eder. Sosyal medya, hemen hemen hiç hedeflemeyle mevcut kullanıcıların ötesinde erişim sağlar.

Kanal	En iyi olduğu yer	Zayıflık
Changelog / feed	Kalıcı kayıt; kendi ritminde kontrol eden okuyucular	Pasif; hiç kontrol etmeyene faydasız
Uygulama içi bildirim	Zaten orada olan, bugün harekete geçecek kullanıcılar	Şu anda oturum açmamış hiç kimseye ulaşmaz
E-posta	Şu anda aktif olmayan ama bunun için geri dönecek kullanıcılar	Diğer e-postaların altında kolayca kaybolur; gerçek bir konu satırı gerekir
Sosyal medya	Mevcut kullanıcıların ötesinde erişim	Hemen hemen hiç hedefleme yok; kısa ömürlü

Dördünden hiçbiri tek başına yeterli değildir. Changelog, boyutuna bakılmaksızın her sürümü taşıması gereken tek belgedir, çünkü diğer her şeyin geri işaret ettiği kayıttır; diğer üçü, özelliğin gerçekte ne kadar büyük olduğuna göre seçilen, üzerine eklenmiş güçlendirmedir.

Duyuru önce ne söylemeli?

Mekanizma değil, sonuç. "Raporlar endpoint'ine bir önbellek katmanı ekledik", ekibin ne inşa ettiğini anlatır. "Raporlar artık bir saniyeden kısa sürede yükleniyor", okuyucu için neyin değiştiğini anlatır, ve tıklamayı sağlayan cümle de budur, çünkü "bundan bana ne" sorusunu üçüncü yerine ilk cümlede yanıtlar. Mekanizma, başlığa değil, changelog girişine veya ayrıntı sayfasına aittir.

Sıfatlardan önce somutluk. "Daha hızlı, daha güçlü bir rapor deneyimi", okuyucuya üzerinde işlem yapabileceği hiçbir şey söylemez; "raporlar artık bir saniyeden kısa sürede yükleniyor ve duruma göre filtrelenebiliyor" tam olarak neyin değiştiğini ve ne denenmesi gerektiğini söyler. İkinci versiyon aynı zamanda daha inandırıcı da görünür, çünkü belirsiz bir iddia, söylenecek somut bir şey olmadığında pazarlama metninin tam olarak kulağa geldiği gibi gelir.

Bir ürün güncelleme e-postasından nasıl farklıdır?

Örtüşür ama aynı değildir. Ürün güncelleme e-postası, sıklık, konu satırları, ve ne zaman bir özetin tek seferlik bir gönderiyi geçtiği dahil, e-posta kanalını özel olarak ele alır. Yeni bir özellik duyurusu, altta yatan olaydır; e-posta, özellik bir sonraki özette taşınmak yerine özel bir gönderiyi haklı çıkaracak kadar büyük olduğunda seçilen, onu taşıyabilecek yukarıdaki dört kanaldan biridir. Küçük bir özellik bir changelog girişini ve belki bir uygulama içi bildirimi hak eder. Önemli bir özellik, zamanlanmış olarak dört kanalın hepsini hak eder.

Tam olarak isteyen kişilere nasıl ulaşılır?

Bu, çabaya karşı en iyi getiriye sahip duyurudur, ve neredeyse tüm ekipler onu atlar. On müşteri bir özelliği isimle istediyse, o on kişi, çıkan başka herhangi bir daha geniş duyurudan bağımsız olarak, gönderildiği anda doğrudan, kişisel bir not hak eder. Müşteriyle geri bildirim döngüsünü kapatmak mekaniği baştan sona ele alır; buradaki özet, bunun sadece orijinal talep talep edene bağlı kaldığında işe yaramasıdır, ki bu bir duyuru sorunundan çok bir takip sorunudur. changeloop'ta, widget geri bildirimi bir GitHub issue'suna dönüştüğünde ve merge edilen pull request onu kapattığında (fixes #142), changelog girişini onaylamak o issue'ya canlı girişe geri bağlanan tek seferlik bir "Shipped — " yorumu yayımlar, ve geri bildirimi gönderen kişi gönderilen girişi widget'ta görür. Kimsenin söylemeyi hatırlaması gerekmez. Elle açılan issue'lar ve GitLab ya da Bitbucket repository'leri bu yorumu almaz.</p> <h2>Girişin kendisi nasıl yazılır?</h2> <p>Diğer herhangi bir sürüm notu girişiyle aynı disiplin: okuyucunun artık yapabileceğiyle başla, gerekli kurulumla devam et, iç gerekçeyi atla. <a href="https://changeloop.dev/blog/tr/how-to-write-release-notes/">Sürüm notları nasıl yazılır</a> tam yöntemi ele alır; yeni bir özellik duyurusu en yüksek riskli durumdur, çünkü ekran görüntüsü alınma, iletilme ve ürünün changelog'unu hiç görmemiş biri tarafından okunma olasılığı en yüksek girişdir.</p> <h2>Ne zaman geniş çapta duyurulmamalı?</h2> <p>Özellik hâlâ hesapların bir alt kümesine yayılıyorsa, gerçekten bir beta ise, veya geniş bir duyurunun on okuyucusundan dokuzunun henüz kullanamayacağı şekilde fiyatlandırılmış veya kilitlenmişse. On okuyucusundan dokuzunun kullanamayacağı bir özellik için geniş bir duyuru bir yem gibi okunur, ve bu duyuruda heyecan yaratmaktan çok bir sonraki duyuruya olan güveni yakar. Çözüm sessizlik değil, kapsamdır: uygun hesapları doğrudan bilgilendirin ve kullanılabilirlik duyuruyu yakalayana kadar geniş kanalları bekletin.</p> <h2>FAQ</h2> <p><strong>Her yeni özellik kendi duyurusunu hak eder mi?</strong> Her biri bir changelog girişini hak eder. Sadece birinin ürünü kullanma şeklini değiştirecek kadar önemli olanlar, veya isimle açıkça istenenler, e-posta veya sosyal medya gibi daha geniş kanalları hak eder.</p> <p><strong>Küçük bir özellik için en iyi kanal nedir?</strong> Sadece changelog, artı özellik kullanıcının zaten içinde olduğu bir akışta keşfedilebilirse bir uygulama içi bildirim. E-posta ve sosyal medya, dikkat istemeyi haklı çıkaran özellikler için değerlidir.</p> <p><strong>Bir özellik, tam olarak isteyen kişilere nasıl duyurulur?</strong> Talebi kaydedildiği andan itibaren talep edene bağlı tutun, sonra gönderildiğinde herhangi bir daha geniş duyurudan ayrı olarak bireysel olarak bildirin. Talep edenin kendi başına kontrol edebileceği paylaşılan bir durum etiketi de baştan kaç bireysel mesaja ihtiyaç duyulduğunu azaltır.</p> <p><strong>Bir özellik duyurusunun ekran görüntüsüne ihtiyacı var mı?</strong> Görsel olan her şey için evet; anlatılan ama görülmeyen bir özellik, okuyucuların önizlemesini görebildiği bir özellikten çok daha sık atlanır. Bir API veya backend yeteneği için, kısa bir kod örneği, bir UI değişikliği için bir ekran görüntüsüyle aynı işi görür.</p> </article> <article> <h1>Birikmiş özellik taleplerine öncelik vermek</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Özellik taleplerini takip etmek, nerede yaşadıklarını çözer. Sırada hangisinin gideceğini çözmez, ve ekiplerin gerçekten takıldığı ikinci soru budur. Gruplanmış, etiketlenmiş üç yüz taleplik bir birikim bile hâlâ bir karar kuralına ihtiyaç duyar, çünkü "en çok istenen şeyi yap" ancak iki talep birbirine yakın olana ve üçüncüsünün gürültülü bir savunucusu olana kadar işe yarar, ki bu haftaların çoğunda böyledir. Aşağıdaki çerçeveler aynı soruya rakip yanıtlar değildir. Her biri farklı bir talep türüne uyar, ve hepsi için tek bir çerçeve kullanmak genellikle asıl hatadır.</p> <h2>Özellik taleplerine öncelik vermeyi bir roadmap'e öncelik vermekten farklı kılan nedir?</h2> <p>Bir roadmap kararı stratejiden başlar ve neyin inşa edileceğini sorar. Bir özellik talebi kararı zaten var olan bir talepten başlar ve buna göre hareket edilip edilmeyeceğini sorar, ve ikisi yeterince sık farklı yönlere çeker ki bir talebin yüksek talebi olabilir ve yine de inşa edilmesi yanlış olabilir, veya düşük talebi olabilir ve yine de stratejik bir hesabı açtığı için değerli olabilir. Her talebi bir roadmap oyu gibi ele almak bu kontrolü atlar.</p> <table> <thead> <tr> <th>Çerçeve</th> <th>Neyi tartar</th> <th>Nerede kırılır</th> </tr> </thead> <tbody><tr> <td>Ham talep sayısı</td> <td>Kaç kişinin istediği</td> <td>Gerçek talep yerine akılda kalan isimleri ödüllendirir</td> </tr> <tr> <td>RICE</td> <td>Kapsam, etki, güven, çaba</td> <td>Yeni bir talep için kimsenin sahip olmadığı tahminlere ihtiyaç duyar</td> </tr> <tr> <td>Gelire göre ağırlıklandırılmış</td> <td>Kimin istediği, hesap değerine göre</td> <td>Henüz çok değerli olmayan hesaplardan gelen talepleri görmezden gelir</td> </tr> <tr> <td>Kamuya açık oylar</td> <td>Görünür, düşük çaba gerektiren sinyal</td> <td>Sadece nereye bakacağını zaten bilen kullanıcılara ulaşır</td> </tr> </tbody></table> <h2>RICE nedir, ve özellik talepleri için işe yarar mı?</h2> <p><a href="https://www.intercom.com/blog/rice-simple-prioritization-for-product-managers/">RICE</a> bir fikri kapsam, etki, güven ve çaba üzerinden puanlar, sonra karşılaştırılabilir bir sayı elde etmek için ilk üçü dördüncüye böler. Bir ekibin zaten inandığı roadmap fikirleri için tasarlanmıştır, ve zor kısım farklı bahisleri birbiriyle karşılaştırmaktır. Özellik talepleri zaten bir kapsam sayısıyla gelir, isteyen kişi sayısı, ki bu yeni bir roadmap fikrinin genelde sahip olduğu kapsamdan daha somuttur. RICE'ın bir talep karşısında gerildiği yer güven ve etkidir: bir ekip bir talebin gerçek olduğundan emin olabilir ve yine de bir metriği ne kadar hareket ettireceğine dair bir temeli olmayabilir, çünkü zaten bir ismi ve gerçek kullanıcı izi olan bir talep için "etki", odanın dışında henüz kimsenin görmediği bir fikrin etkisinden farklı bir tahmin türüdür.</p> <p>RICE'ı ciddi olarak değerlendirilen ve henüz karara bağlanmamış talepler için kullan. Gelen her talebe uygulama; puanlama çabası ancak eşitlik bozucuya ihtiyaç duyacak kadar birbirine yakın olanlarda karşılığını verir.</p> <h2>Gelire göre mi, yoksa kimin istediğine göre mi ağırlıklandırılmalı?</h2> <p>Kimin istediğine göre, ama sadece gelire göre değil. Yenilemeye yakın bir hesap, daha önce eskalasyon yapmış bir hesap, ve talebi devam eden bir anlaşmayı açan bir hesap, düz bir gelir rakamının tek başına yakalayamadığı bir aciliyet taşır, ve deneme kaydından gelen bir talep, yakında gelire dönüşecek bir kararı engelliyorsa yine de önemli olabilir. Gelire göre ağırlıklandırma bunların hesaplanması en kolay olanıdır, ve tam da bu yüzden fazla güvenilmesi en kolay olanıdır: gerçek payı olmayan hesaplardan gürültüyü doğru şekilde kaldırır, ve aynı kolaylıkla hâlâ boru hattında olan çok daha büyük bir hesabı kazandıracak bir talebi de düşürebilir.</p> <h2>Oylar gerçekte hangi rolü oynar?</h2> <p>Zaten var olan talepler için ucuz, sürekli bir sinyal, ve hangi taleplerin en başta var olması gerektiğini keşfetmek için kötü bir yol. Bir oy sayısı sadece talebi zaten bulmuş ve tıklamaya değer bulmuş kullanıcılara ulaşır, ki bu, kamuya açık bir roadmap'in oy toplamının talep kadar görünürlüğü de yansıttığı anlamına gelir: listenin üstüne yakın eski bir talep, kısmen bulunması kolay olduğu için oy toplamaya devam eder, ve daha yeni, eşit derecede gerçek bir talep sıfırdan başlar. <a href="https://changeloop.dev/blog/tr/public-roadmap/">Genel roadmap</a> yazısı, oyları roadmap'in tamamen dışında bırakmayı savunur. Oyları, sırayla inşa edilecek bir sıralama olarak değil, gruplanması ve güncelliğe göre ağırlıklandırılması gereken bir girdi olarak ele al. <a href="https://changeloop.dev/blog/tr/feedback-signal-quality/">Destek biletleri vs. özellik talepleri</a> oy sayılarındaki diğer kör noktayı ele alır: ona rastlayan kullanıcılar panoyu asla bulamazsa gerçek bir boşluk neredeyse hiç oy üretmeyebilir, buna karşın destekte gürültülü bir şekilde ortaya çıkar.</p> <h2>En gürültülü müşteri ne zaman kazanır, ve bu bir sorun mu?</h2> <p>Bazen, ve bu sadece kimse fark etmediğinde bir sorundur. Sık sık eskalasyon yapan, ayrıntılı biletler yazan veya ekipteki biriyle doğrudan hattı olan bir müşteri, talepleri eşit derecede geçerli ama daha sessiz bir müşteriden daha hızlı görülecektir, ve bunu hiç kontrol etmeyen bir önceliklendirme süreci, en güçlü davası olanı değil, en çok ısrar edeni sistematik olarak kayıracak demektir. Gürültülü müşteriler düzeltilmesi gereken sorun değildir; talepleri genellikle gerçekten önemlidir. Düzeltme bir alışkanlıktır: birikimi periyodik olarak kaynağa göre gözden geçir ve aynı avuç içi kadar hesabın son zamanlarda gönderilenlerin çoğunu açıklayıp açıklamadığını kontrol et, ve bunun gerçek talebin nerede olduğuyla eşleşip eşleşmediğini sor.</p> <h2>Bir önceliklendirme kararı nasıl bir yanıta dönüşür?</h2> <p>Buradaki her karar hem kazananlar hem de kaybedenler üretir, ve ikisi de sadece açıklamasız bir durum değişikliği değil, gerçek gerekçeyi adlandıran bir yanıtı hak eder. <a href="https://changeloop.dev/blog/tr/declining-feature-requests/">Bir özellik talebi nasıl reddedilir</a> kaybeden bir talebe, jenerik bir ret gibi okunmak yerine ilişkiyi sağlam tutan bir şekilde ne söyleneceğini ele alır. Tüm bunları en başta mümkün kılan gruplama ve etiketleme işi <a href="https://changeloop.dev/blog/tr/feature-request-tracking/">özellik talebi takibi</a> yazısında ele alınır; önceliklendirme yalnızca zaten kaydedilmiş ve karşılaştırılabilecek kadar iyi gruplanmış talepler üzerinde işe yarar.</p> <h2>FAQ</h2> <p><strong>Özellik taleplerine öncelik vermek için en iyi çerçeve nedir?</strong> Hiçbiri tek başına değil. En gürültülü sinyali bulmak için ham sayıları, kısa bir ciddi aday listesini karşılaştırmak için RICE'ı, ve stratejik bir hesaptan gelen sessiz talebin daha gürültülü ama daha az önemli bir grubu geride bıraktığı durumları yakalamak için bir gelir veya hesap kontrolünü kullan.</p> <p><strong>Özellik talepleri roadmap fikirleriyle aynı şekilde mi önceliklendirilmeli?</strong> Hayır. Roadmap fikirleri stratejiden başlar; özellik talepleri zaten var olan bir talepten başlar. Onları birlikte puanlamak, iyi savunulmuş ama az mevcut talebi olan stratejik bir bahsin, sadece daha fazla kişinin istediği bir talep karşısında sürekli kaybetmesine neden olur.</p> <p><strong>Genel bir roadmap'teki oylar talebi doğru şekilde yansıtır mı?</strong> Sadece talebi zaten bulmuş kişiler arasında. Daha eski, daha görünür talepler, arkalarında daha yeni bir talep için gerçek talebin ne kadar olduğuna bakılmaksızın daha hızlı oy toplar, bu yüzden oy toplamlarını sırayla inşa edilecek bir sıralama olarak değil, gruplanmış ve güncelliğe göre ağırlıklandırılmış bir sinyal olarak ele al.</p> <p><strong>Özellik talebi öncelikleri ne sıklıkla yeniden değerlendirilmeli?</strong> Sadece biri eskalasyon yaptığında değil, sabit bir döngüde. Talepleri yeniden gruplayan ve ağırlıklandırmayı yeniden kontrol eden aylık veya üç aylık bir geçiş, gönderilenlere hakim olan bir avuç hesap gibi, saf reaktif bir sürecin kendi kendine asla ortaya çıkarmadığı sapmaları yakalar.</p> </article> <article> <h1>Kurumsal release notları: bir hesap için ne değişir</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Genel bir SaaS ürünü herkese aynı release notes'u gönderir, çünkü herkes aynı sürümdedir. Sabitlenmiş bir sürümdeki, ayrılmış bir örnekteki, veya ürünün özellik bayraklı bir alt kümesindeki kurumsal bir müşteri bu varsayımı bozar: onun için neyin değiştiğini açıklayan release notes, genel blogunuzdakilerle aynı değildir, ve yine de genel olanları göndermek ya müşteriyi henüz sahip olmadığı değişikliklerle karıştırır, ya da daha kötüsü, başka bir kurumsal müşterinin hesap ekibinin kendi hesaplarından bir ay daha geri tutmanızı özellikle istediği bir özellikten ona bahseder. <a href="https://changeloop.dev/blog/tr/release-notes-best-practices/">Release notes en iyi uygulamaları</a> genel zanaatı ele alır; bu, müşterilerinizin hepsi aynı build üzerinde olmadığında ortaya çıkan ayarlama sorunu için kurumsal release notları yazmakla ilgilidir.</p> <h2>Kurumsal bir müşteri neden basitçe genel changelog'u okuyamaz?</h2> <p>Çünkü henüz çalıştırmıyor olabileceği bir sürümü, erişimi olmayabileceği özellikleri, ve kendisininkiyle eşleşmeyen bir zaman çizelgesini tanımlar. Üç aylık bir sürüm döngüsüne sabitlenmiş ve geçen hafta genel katmana çıkan bir özellik hakkında okuyan bir müşteri, sadece genel changelog'dan, o özelliğin kendisine gelecek hafta mı yoksa gelecek çeyrekte mi geleceğini bilemez. Genel changelog "üründe ne değişti"ye cevap verir; kurumsal bir müşterinin gerçek sorusu "çalıştırdığım sürümde ne değişti, ve geri kalanını ne zaman alacağım"dır, ki genel changelog buna asla cevap vermek için yazılmamıştır.</p> <h2>Özel bir release note'un genel birinin ihtiyaç duymadığı ne şeye ihtiyacı var?</h2> <p>Müşterinin gerçekten karşılaştırabileceği bir sürüm veya ortam tanımlayıcısı, ve henüz kendisine ulaşmamış olanın açık bir ifadesi. "Bu sürüm, genel 4.3 sürümümüzdeki toplu dışa aktarma iyileştirmelerini içeriyor, ama bir sonraki planlanmış güncellemenizde gelecek yeni izin modelini içermiyor" bir kurumsal yöneticiye örneğinin genel olarak ürüne göre tam olarak nerede durduğunu söyler. Genel bir release note bu çerçevelemeye asla ihtiyaç duymaz çünkü göreceli olunacak sadece bir örnek vardır; özel biri onsuz anlamsızdır.</p> <table> <thead> <tr> <th>Genel release notes</th> <th>Özel (kurumsal) release notes</th> </tr> </thead> <tbody><tr> <td>Bir sürüm, bir kitle</td> <td>Birden fazla sürüm, bölümlenmiş kitleler</td> </tr> <tr> <td>Okuyucunun her açıklanan özelliğe sahip olduğunu varsayar</td> <td>Okuyucunun neye sahip olup olmadığını belirtmeli</td> </tr> <tr> <td>Genel sürüme göre zamanlanır</td> <td>Müşterinin kendi güncelleme penceresine göre zamanlanır</td> </tr> <tr> <td>Hemen tamamen genel yapılabilir</td> <td>Diğer müşterilerin henüz sahip olmadığı öğeleri tutmalı olabilir</td> </tr> </tbody></table> <h2>Genel release notes'u kurumsal müşterilere göndermeyi ayrı yazmak yerine sadece geciktirmek hiç uygun mudur?</h2> <p>Sadece sürümü o anda gerçekten genel olanla eşleşiyorsa, ki bu birden fazla kurumsal hesabınız farklı ritimlerde olduğunda sandığınızdan daha nadirdir. Genel notları geciktirmek, bir sürüm geride olan ve yetişmek üzere olan bir müşteri için geçici bir çözüm olarak işe yarar; iki kurumsal müşteri birbirinden farklı sürümlerde olduğu anda çöker, çünkü artık geciktirilecek tek bir "notlar" yoktur, sadece her birinin sahip olduğunun bir matrisi vardır. O noktada, notları hesap başına ayarlamak, aynı temel girdilerin filtrelenmiş bir görünümü olsa bile, isteğe bağlı olmaktan çıkar.</p> <pre><code>Henüz özelliğe sahip olmayan bir kurumsal hesaba gönderilen genel notlar: "New: Bulk export now supports custom column ordering." (Kafa karıştırıcı: yönetici deniyor ve orada değil.) Aynı hesap için ayarlanmış kurumsal notlar: "Available in your next update (scheduled for 2026-10-15): bulk export with custom column ordering. Not yet available on your current version (3.8)." </code></pre> <h2>Müşterinin organizasyonu içinde bunu gerçekte kim okur, ve bu yazımı değiştirir mi?</h2> <p>Genellikle son kullanıcı yerine bir BT yöneticisi veya bir customer success kişisi, ve bu neyin faydalı sayıldığını değiştirir. Bir son kullanıcı ekranında neyin farklı göründüğünü bilmek ister; kurumsal bir yönetici izinlerde, veri işlemede, SSO yapılandırmasında, veya kendi kullanıcıları için dağıtımı nasıl yönettiğini etkileyen herhangi bir şeyde neyin değiştiğini bilmek ister, çünkü dahili soruları yanıtlayacak kişi o olacaktır. Tüketici changelog'u gibi okunan, hepsi parlak yeni düğmeler ve hiç operasyonel detay olmayan özel bir release note, yöneticiyi gerçekten ihtiyaç duyduğu bilgiyi kazmaya zorlar.</p> <h2>Bu, aynı özelliği zaten listeleyen genel bir roadmap veya genel bir changelog ile nasıl etkileşir?</h2> <p>Dikkatlice, çünkü ikisini de okuyan bir müşteri herhangi bir tutarsızlığı fark edecektir. Genel changelog'unuz zaten belirli bir kurumsal hesabın henüz sahip olmadığı bir özelliği duyurduysa, onun özel release note'u genel girdinin var olmadığını varsaymak yerine bu boşluğu kabul etmelidir; genel duyuruyu görmüş ve onu görmezden gelen özel notlar alan bir yönetici ya onu unuttuğunuzu ya da bir şeyin bozuk olduğunu varsayacaktır. <a href="https://changeloop.dev/blog/tr/public-roadmap/">Genel roadmap</a> neyin çıktığına karşı neyin planlandığına dair bir roadmap'i dürüst tutmayı ele alır; bu dürüstlüğün release notes'taki kurumsal versiyonu, genel olan ile kendisininki arasındaki boşluğu doğrudan adlandırmaktır.</p> <h2>Sadece bir veya iki kurumsal müşterisi olan küçük bir şirketin bu kadar yapıya ihtiyacı var mı?</h2> <p>Tamamen bölümlenmiş sisteme değil, ama temel disiplin, müşterinin hangi sürümde olduğunu ve neye sahip olup olmadığını açıkça belirtmek, en son build'inizde olmayan bir müşteriniz olur olmaz her ölçekte önemlidir. Bunun önlediği başarısızlık modu, genel bir duyurunun kendisine uygulanıp uygulanmadığı konusunda kafası karışan bir yönetici, ister iki kurumsal hesabınız olsun ister iki yüz, bir destek bileti ve güvene bir darbe maliyetlidir.</p> <h2>FAQ</h2> <p><strong>Özel release notes, diğer müşterilerin zaten sahip olduğu ama bunun sahip olmadığı özelliklerden hiç bahsetmeli mi?</strong> Sadece kendi zaman çizelgesiyle ilgiliyse, "bir sonraki güncellemenizde geliyor" olarak ifade edilerek, diğer müşterilerle bir karşılaştırma olarak değil. Belirli bir başka müşterinin sahip olduğunu adlandırmak, sizin ifşa etmeniz gerekmeyen bir bölgeye girer; bu müşteriye özellikle neyin geleceğini adlandırmak tam olarak ihtiyaç duyduğu bilgidir.</p> <p><strong>Aynı temel changelog girdileri hem genel hem de özel release notes'u besleyebilir mi?</strong> Evet, ve bu genellikle daha sürdürülebilir yaklaşımdır: girdileri hangi sürümlere veya katmanlara uygulandıklarıyla etiketleyin, sonra kaçınılmaz olarak birbirinden ayrışacak tamamen ayrı iki belge yazmak yerine yayımlama sırasında kitleye göre filtreleyin.</p> <p><strong>Bir kurumsal müşteri özel bir feed yerine genel release notes'ta olmayı açıkça isterse ne olur?</strong> Buna saygı gösterin, ama genel notların genel sürümü varsaydığını anladığından emin olun, ve sürümü açıklanandan farklıysa boşluğu kendiniz yazılı olarak işaretleyin. Bu yazılı onay, gerçekte kendi build'ine uygulanmayan genel notlara göre hareket ederse sizi daha sonra korur.</p> <p><strong>Kurumsal bir müşteriye, bir sonraki sürümde erişeceği bir özellik hakkında ne kadar önceden bilgi verilmeli?</strong> Sadece sürüm zamanında değil, tarih onaylanır onaylanmaz, çünkü kurumsal yöneticiler genellikle gelen bir özellik etrafında kendi dahili iletişimlerini veya eğitimlerini planlamalıdır, ve aynı gün bildirimi bunun için onlara hiç alan bırakmaz.</p> </article> <article> <h1>Semantic versioning ve changelog'unuz</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Semantic versioning, çağıran tarafa bir sürümün tek bir changelog girişi okumadan önce ne kadar canını yakabileceğini söyler. <code>2.4.1</code>'den <code>2.5.0</code>'a geçmek şunu söyler: yeni yetenek, hiçbir şey bozulmaz. <code>2.5.0</code>'dan <code>3.0.0</code>'a geçmek şunu söyler: güncellemeden önce bu girişi oku. Changelog ve sürüm numarası, aynı şeyi iki biçimde iddia etmesi gereken şeylerdir, ve ikisi arasındaki sürtünmenin çoğu tam olarak uyuşmadıklarında ortaya çıkar, ki bu spesifikasyonun ima ettiğinden daha sık olur.</p> <h2>Bir versiyondaki her sayı gerçekte ne vaat eder?</h2> <p><a href="https://semver.org/">Semantic versioning</a>, her biri neyi tetiklediğine dair katı bir kurala sahip üç sayı tanımlar: <code>MAJOR.MINOR.PATCH</code>. Bir MAJOR sıçraması, uyumsuz bir değişiklik anlamına gelir: doğru, mevcut bir entegrasyonun fark edebileceği ve bu yüzden değişmesi gereken bir şey. Bir MINOR sıçraması, geriye dönük uyumlu yeni işlevsellik anlamına gelir: mevcut hiçbir şey bozulmaz, yeni bir şey kullanılabilir olur. Bir PATCH sıçraması, geriye dönük uyumlu bir düzeltme anlamına gelir: davranış belgelenmiş olana daha yakınlaşır, ve eski davranışa kasıtlı olarak güvenen hiç kimse hiçbir şey fark etmemelidir.</p> <table> <thead> <tr> <th>Sıçrama</th> <th>Anlamı</th> <th>Giriş şöyle okunmalı</th> </tr> </thead> <tbody><tr> <td>MAJOR (<code>1.x.x</code> -> <code>2.0.0</code>)</td> <td>Uyumsuz bir değişiklik</td> <td>"Güncellemeden önce eylem gerekir"</td> </tr> <tr> <td>MINOR (<code>1.2.x</code> -> <code>1.3.0</code>)</td> <td>Yeni, uyumlu yetenek</td> <td>"Şimdi kullanılabilir, başka bir şey değişmedi"</td> </tr> <tr> <td>PATCH (<code>1.2.3</code> -> <code>1.2.4</code>)</td> <td>Uyumlu bir düzeltme</td> <td>"Artık belgelendiği gibi davranıyor"</td> </tr> </tbody></table> <p>Tablo, geriye doğru da bir testtir: bir giriş kendi satırı gibi okunmuyorsa, ya sürüm numarası yanlıştır ya da giriş gerçekte ne olduğunu az veya çok satmaktadır.</p> <h2>Sürümleme amaçları için ne uyumsuz sayılır?</h2> <p>Bir şeyin API changelog'una ait olup olmadığına karar veren aynı test: eski davranışa karşı yazılmış ve o zamandan beri dokunulmamış doğru bir çağıran, bu değişiklik yüzünden farklı davranabilir mi. <a href="https://changeloop.dev/blog/tr/breaking-changes/">Uyumsuz bir değişiklik nedir, ve nasıl gönderilir</a> kararı baştan sona ele alır, uyumsuz görünüp öyle olmayan ve küçük görünüp öyle olmayan durumlar dahil. Sürümleme için kısacası: yanıt evetse, değişikliğin dahili olarak gerçekte ne kadar kod etkilediğine bakılmaksızın sıçrama MAJOR'dır. Sürüm numaraları, ekibin çabasını değil, çağıran için sonucu takip eder.</p> <h2>Bir changelog girişi bir sürüm sıçramasına nasıl uymalı?</h2> <p>Bir giriş, bir sıçrama kategorisi, en baştan belirtilmiş. Tablodaki desen doğrudan devam eder: uyumsuz bir giriş, onu tanıtan sürümün altında yer alır, önce uyarı sonra açıklama olarak ifade edilir. Ek bir giriş, MINOR sürümünün altında yer alır, kullanılabilirlik olarak ifade edilir. Bir düzeltme, PATCH sürümünün altında yer alır, düzeltme olarak ifade edilir. Kategorileri bir girişte karıştırmak, örneğin uyumsuz bir değişikliği ilgisiz bir düzeltmeyle aynı paragrafa katlamak, bir okuyucunun gerçekten önemli olan tek şeyi tam olarak kaçırmasının yoludur.</p> <pre><code>## 3.0.0 (2026-09-07) ### Changed - **BREAKING:** `GET /reports` artık tutarları ondalık yerine en küçük para birimi cinsinden (kuruş) tam sayı olarak döndürüyor. `amount`'ı doğrudan okuyan kodu güncelleyin. ## 2.9.0 (2026-09-01) ### Added - Raporlar artık `status`'a göre filtrelenebilir. ## 2.8.4 (2026-08-28) ### Fixed - `GET /reports?status=`, bilinmeyen bir durum için 400 yerine boş bir sayfa döndürüyordu. </code></pre> <p>Yukarıdan aşağıya okunduğunda, sürüm numarası ve bölüm etiketi aynı şeyi iki kez söyler, ve amaç tam olarak budur: sadece başlıkları tarayan bir okuyucu, tek bir satır açmadan doğru bir risk okuması alır.</p> <h2>Breaking change kuralı 1.0.0'dan önce de aynı şekilde geçerli mi?</h2> <p>Hayır, ve "bu gerçekten breaking mıydı" konusundaki kafa karışıklığının çoğu buradan gelir. SemVer, sıfırıncı majör sürümün, <code>0.y.z</code>, ilk geliştirme için olduğunu açıkça belirtir: her şey her an değişebilir, ve public API kararlı sayılmamalıdır. Bir <code>0.4.0</code>'dan <code>0.5.0</code>'a sıçrama, spesifikasyonu ihlal etmeden breaking bir değişiklik taşıyabilir, çünkü majör sürüm garantisi ancak bir proje <code>1.0.0</code>'ı gönderdiğinde başlar. Bir changelog girişi yine de okuyuculara neyin bozulduğu konusunda aynı dürüstlüğü borçludur; değişen tek şey, 1.0.0'a ulaşmadan önce sürüm numarasının kendisinin güvenilecek sinyal olmamasıdır.</p> <h2>Ürününüz ayrık sürümler göndermiyorsa ne olur?</h2> <p>Çoğu SaaS ürünü sürekli olarak dağıtır ve çağıran tarafa asla bir sürüm numarası göstermez, ki bu disiplin ihtiyacını ortadan kaldırmaz, sadece onu normalde taşıyacak sayıyı kaldırır. Changelog girişi tüm işi tek başına yapmalıdır: bir değişikliğin uyumsuz mu, ek mi, yoksa bir düzeltme mi olduğunu, semantic versioning'in kullandığı aynı üç kelimeyle, hatta onları takacak bir sürüm alanı olmadan bile açıkça söylemek. Bazı ekipler, changelog girişlerini asla doğrudan çağıran tarafa göstermeden, sadece bağlantı verilebilir bir şeye çapalamak için tamamen dahili bir sürüm tutar.</p> <h2>Bu, özellikle bir API changelog'una nasıl uygulanır?</h2> <p>Neredeyse başka her yerden daha katı bir şekilde, çünkü bir API'nin çağıranları koddur, beklenmedik bir değişikliği omuz silkip geçebilecek insanlar değil. <a href="https://changeloop.dev/blog/tr/api-changelog/">API changelog'u: ne yayınlanır ve kim okur</a> o belgenin tam biçimini ele alır; buradaki sürümleme disiplini, onun breaking ve ek bölümlerini dürüst tutan şeydir. Bir geçiş penceresi sırasında <code>v1</code> ve <code>v2</code>'yi paralel sunmak gibi birden fazla sürümü aynı anda sunan bir API, tek bir paket yerine tüm arayüz ölçeğinde etkin bir şekilde semantic versioning uyguluyordur, ve aynı üç kelimelik kelime dağarcığı her giriş için hâlâ geçerlidir.</p> <h2>Keep a Changelog sürümleme hakkında ne söylüyor?</h2> <p>Doğrudan ismiyle semantic versioning'e bağlanır ve bu makalenin kullandığı aynı kategori kelime dağarcığını önerir: Added, Changed, Deprecated, Removed, Fixed, Security. <a href="https://changeloop.dev/blog/tr/keep-a-changelog-implemented/">Keep a Changelog, uygulamada</a> ekiplerin genelde nerede saptığı dahil, bu spesifikasyonu benimsemeyi ele alır. Örtüşme tesadüf değildir: her iki spesifikasyon da aynı sorunu zıt uçlardan çözmeye çalışır, biri sürüm numarasını standartlaştırır, diğeri onu açıklayan girişi.</p> <h2>FAQ</h2> <p><strong>Her changelog girişinin bir sürüm numarasına ihtiyacı var mı?</strong> Ürün sürümler gönderiyorsa evet, çünkü sayı bir okuyucunun önce girişi okumadan doğrudan "bu beni ne kadar etkiliyor"a atlamasına izin verir. Ürün sürüm alanı olmadan sürekli olarak dağıtılıyorsa, girişin ifadesi bu sinyali tek başına taşımalıdır.</p> <p><strong>MAJOR sıçraması ile uyumsuz değişiklik girişi arasındaki fark nedir?</strong> Aynı olayı iki şekilde tanımlamalıdırlar. Sürüm numarası makine tarafından okunabilir sinyaldir (çağıranın araçları buna tepki verebilir); changelog girişi, tam olarak neyin değiştiğinin insan tarafından okunabilir açıklamasıdır.</p> <p><strong>Bir PATCH sürümü uyumsuz olabilir mi?</strong> Tanım gereği olmamalıdır. Yine de biri yayınlandıysa, yayınlanan sürümü düzenlemeyin veya yeniden etiketlemeyin: <a href="https://semver.org/#what-do-i-do-if-i-accidentally-release-a-backward-incompatible-change-as-a-minor-version">SemVer FAQ</a> uyumluluğu geri getiren yeni bir sürüm, ya da kırılma kalıyorsa yeni bir MAJOR yayınlamayı ve kullanıcıların atlaması gerektiğini bilmesi için sorunlu sürümü belgelemeyi söyler.</p> <p><strong>Tamamen dahili değişikliklerin bir sürüm sıçramasına ihtiyacı var mı?</strong> Hayır. Semantic versioning herkese açık arayüzü takip eder. Çağıran için gözlemlenebilir bir etkisi olmayan bir yeniden düzenleme, önemli bir mühendislik çalışması olsa bile ne bir sıçramaya ne de bir changelog girişine ihtiyaç duyar.</p> </article> <article> <h1>Changelog nedir? Örnek bir kayıtla açıklama</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Changelog, bir üründe neyin değiştiğinin tarihli kaydıdır ve değişikliği gönderen ekip için değil, değişiklikten etkilenen kişiler için yazılır. Her giriş bir değişikliği adlandırır, ne zaman yürürlüğe girdiğini söyler ve okuyucunun bununla ilgili ne yapması gerektiğini söyler, ki girişlerin çoğunda bu hiçbir şeydir. Bir changelog'u commit log'undan ayıran tam olarak bu son kısımdır: commit log, kodu yazanlar için bir kayıttır; changelog, onu kullananlar için bir kayıttır.</p> <h2>Changelog tam olarak nedir?</h2> <p>Tarihli girişlerin bir listesi, en yeni en üstte, her biri tek bir değişikliği okuyucunun üzerinde işlem yapabileceği terimlerle anlatır. Ekibin ne inşa ettiği değil, şimdi neyin farklı olduğu. "Faturalama servisi yeniden düzenlendi" bir commit mesajıdır. "Faturalar artık vergiyi ayrı bir satır olarak gösteriyor" bir changelog girişidir, çünkü okuyucuya kendi hesabında doğrulayabileceği bir şey söyler.</p> <p>Format eskidir ve bilinçli olarak sadedir: her sürüm veya gün için bir başlık, altında kısa bir liste, bazen bir kategori etiketi. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a>, bu biçim için en çok atıf alan spesifikasyondur ve bir spesifikasyonu atlayan çoğu projenin sonunda onun yerine commit geçmişini döktüğü için var olur, ki bu da okuyucunun geldiği sorudan farklı bir soruyu yanıtlar.</p> <table> <thead> <tr> <th>Belge</th> <th>Kimin için yazılır</th> <th>Neyi yanıtlar</th> </tr> </thead> <tbody><tr> <td>Changelog</td> <td>Ürünü kullanan herkes</td> <td>Ne değişti, ve ne zaman?</td> </tr> <tr> <td>Commit log</td> <td>Kodu yazan ekip</td> <td>Ne yapıldı, hangi sırayla?</td> </tr> <tr> <td>Sürüm notları</td> <td>Güncelleme kararı veren kullanıcılar</td> <td>Artık ne yapabiliyorum?</td> </tr> <tr> <td>Yama notları</td> <td>Belirli bir düzeltmenin kullanıcıları</td> <td>Bu sürüm tam olarak neyi düzeltti?</td> </tr> <tr> <td>Yol haritası</td> <td>Sırada ne olduğunu merak eden herkes</td> <td>Ne planlanıyor, ve ne kadar ilerledi?</td> </tr> </tbody></table> <p>Bu beşi pratikte örtüşür, ama aynı belge değildir, ve fark, okunduğu anda kimin elinde tutulduğundadır. Changelog, aranmak ve sonradan tekrar bağlantı verilmek için inşa edilmiş olandır, bu yüzden girişleri diğerlerinden daha çok sabit tarihlere ve URL'lere ihtiyaç duyar.</p> <h2>Bir changelog girişi gerçekte neyi içerir?</h2> <p>Sırasıyla dört şey: neyin değiştiği, kullanıcının veya çağıran tarafın fark edeceği terimlerle ifade edilmiş; ne zaman yürürlüğe girdiği; hangi kategoriye ait olduğu (added, fixed, changed, removed yaygın dört kategoridir); ve önemli olduğunda, okuyucunun bununla ilgili ne yapması gerektiği. Daha fazla ayrıntıya bir bağlantı hoş karşılanır. Bir iç gerekçe paragrafı değil, çünkü okuyucu nedenini sormadı, neyi sordu.</p> <pre><code>## 2026-09-07 ### Added - Faturalar artık müşterinin hesap para biriminde, vergiyi ayrı bir satır olarak gösteriyor. ### Fixed - Bir raporu CSV olarak dışa aktarmak, rapor 10.000 satırı aştığında artık son satırı düşürmüyor. </code></pre> <p>Bu biçim, iki satırlık bir güncellemeden bir sürümdeki yüz girişe kadar, yapıyı değiştirmeden ölçeklenir, ve bir formatın işe yarayıp yaramadığının gerçek testi de budur: yoğun bir haftada da sakin bir haftada da aynı şekilde okunuyor mu.</p> <h2>Changelog'u kim yazar, ve ne zaman?</h2> <p>Değişikliği yapan kişi, gönderildiği anda, bir hafta sonra biletlerden yeniden inşa eden teknik bir yazar değil. Koda dokunan kişi, kullanıcı için gerçekte neyin değiştiğini bilir; sonradan yazılan bir özet, gerçekte gönderilen şey yerine bileti anlatma eğilimindedir, ve bu genellikle gerçek kapsamdan daha geniş ya da daha dardır. Bazı ekipler bir giriş herkese açık olmadan önce bir inceleme adımı ekler, çoğunlukla içeri sızmış iç dil kullanımını yakalamak için, ve bu inceleme, giriş aynı gün yayınlanacak kadar hızlı olmalıdır.</p> <h2>Changelog nerede durmalı?</h2> <p>Kendi sayfasında, sabit bir URL'de, feed olarak dağıtılmış. Bir ayarlar menüsüne veya bir kod barındırıcısındaki bir release etiketine gömülmüşse, sadece nereye bakacağını zaten bilenlere ulaşır. Herkese açık bir sayfa bir destek biletinden bağlanabilir, bir incelemede alıntılanabilir veya abone olunabilir. Feed, sayfa kadar önemlidir: bir ürünün changelog'unu ayda bir kontrol eden bir okuyucu nadirdir, ona abone olan biri değildir, ve ikinciye sadece feed hizmet eder.</p> <h2>Sürüm notlarından nasıl farklıdır?</h2> <p>İkisi sürekli karıştırılır, ve birbirine karıştırmanın hiçbir okuyucuya iyi hizmet etmeyen bir belge ürettiği kadar da farklıdırlar. <a href="https://changeloop.dev/blog/tr/changelog-vs-release-notes/">Changelog ve sürüm notları</a> farkı baştan sona ele alır; kısacası, changelog eksiksiz, kronolojik kayıttır, sürüm notları ise bir güncellemenin sahip olmaya değer görünmesi için yazılmış küratörlü bir alt kümedir. Bir ürün genelde ikisine de ihtiyaç duyar, okuyucunun gününün farklı anlarına yönelmiş olarak.</p> <h2>Bir changelog'u okunmaya değer kılan nedir?</h2> <p>Kendi kapsamı hakkında somutluk ve dürüstlük. "Çeşitli hata düzeltmeleri", bir okuyucuya sayfayı açmayı bırakmayı öğreten cümledir, çünkü doğrulayabileceği hiçbir şey vaat etmez. Küçük bir düzeltme için bile değişen tam davranışı adlandıran bir giriş, bir aboneliği canlı tutan giriştir. Bu disiplin ihmal edilenler için de geçerlidir: sadece kazanımları duyuran ve bozuk bir şey için asla bir düzeltmeyi duyurmayan bir changelog, changelog kılığına girmiş pazarlama gibi okunur, ve okuyucular bunu fark eder.</p> <p>Sürümleme disiplini de önemlidir. <a href="https://changeloop.dev/blog/tr/semantic-versioning-changelog/">Semantic versioning ve changelog'unuz</a>, sürüm numarasının ve girişin nasıl uyumlu olması gerektiğini gösterir, böylece sürüm geçmişini tarayan bir okuyucu aynı sinyali iki farklı sinyal yerine iki kez alır.</p> <h2>Changelog'lar nasıl üretilir?</h2> <p>İki yolla, ve çoğu gerçek kurulum bir karışımdır. Otomatik üretim commit mesajlarını okur, genelde <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a> formatında, ve kimse çıktıya dokunmadan bunları girişlere dönüştürür; <a href="https://changeloop.dev/blog/tr/conventional-commits-changelog/">conventional commits'ten changelog'a</a> bu iş hattını ele alır. Küratörlü üretim, birinin her girişi elle yazması veya düzenlemesi demektir. Otomatik çıktı daha hızlıdır ve hiçbir zaman birleştirilmiş bir pull request'i kaçırmaz, ama her belirsiz commit mesajını kelimesi kelimesine devralır, bu yüzden otomasyon kullanan çoğu ekip, ham çıktıyı doğrudan göstermek yerine yayınlamadan önce hafif bir düzenleme adımını yine de korur.</p> <h2>FAQ</h2> <p><strong>Her ürünün bir changelog'a ihtiyacı var mı?</strong> Değişiklikten etkilenen kullanıcıları olan her ürünün ihtiyacı vardır, ister SaaS uygulaması, ister dahili bir araç, ister herkese açık bir API olsun. Biçim uyum sağlar (bir API changelog'u bir tüketici uygulamasınınkinden farklı okunur), ihtiyaç sağlamaz.</p> <p><strong>Yazılım terimleriyle changelog nedir?</strong> Yukarıdakiyle aynı tanım: yazılımda neyin değiştiğinin, onu inşa edenler için değil kullananlar için yazılmış tarihli, kronolojik bir listesi.</p> <p><strong>Bir changelog commit'lerden otomatik olarak üretilebilir mi?</strong> Evet, ve birçok ekip tam olarak bunu yapar, genelde Conventional Commits formatındaki mesajlardan. Ödünleşim, üretilen bir girişin geldiği commit mesajı kadar açık olmasıdır, bu yüzden yayınlamadan önceki bir inceleme geçişi yeniden ifade edilmesi gerekenleri yakalar.</p> <p><strong>Changelog bir sürüm geçmişiyle aynı şey midir?</strong> Terimlerin birbirinin yerine kullanılacağı kadar yakın. Bir sürüm geçmişi bazen açıklama olmadan sadece sürüm numaraları ve tarihlerin bir listesidir; changelog her zaman neyin değiştiğini içerir.</p> </article> <article> <h1>Webhook changelog'ları: kimsenin istemediği breaking change</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Bir REST API changelog'u var olur çünkü çağıran anlamadığı bir yanıtı reddedebilir, ya da en azından biri fark edecek kadar gürültülü bir hata loglayabilir. Bir webhook alıcısı bunların hiçbirini nadiren yapar. Bir POST alır, beklediği alanları okur, ve bir alan taşınmış, tipi değişmiş veya kaybolmuşsa, endpoint ya kimsenin izlemediği bir arka plan işinde sessizce çöker ya da, daha kötüsü, hiç doğrulamadığı yanlış bir değerle çalışmaya devam eder. <a href="https://changeloop.dev/blog/tr/breaking-changes/">Breaking change nedir</a> genel tanımı ele alır; bir webhook payload'u kendi cevabına ihtiyaç duyar, çünkü başarısızlık modu birinin bilerek çağırdığı bir endpoint'ten farklıdır.</p> <h2>Bir webhook payload değişikliği bir API yanıt değişikliğinden neden farklı bozulur?</h2> <p>Çünkü isteğin yönü tersine dönmüştür. Bir REST çağıranı çağrıyı başlatır ve bir sürüm başlığı ekleyebilir, 4xx'te yeniden deneyebilir veya yanıtta bir kullanımdan kaldırma bildirimi okuyabilir. Bir webhook alıcısı bunların hiçbirini başlatmadı: sunucunuz göndermeye karar verdi, ne zaman göndereceğine karar verdi, ve gövdenin ne şekilde olacağına karar verdi. Alıcının tek kaldıracı entegrasyon kurulurken yazdığı doğrulamadır, ve çoğu entegrasyon bir kez kurulur, çalışır, ve bozulana kadar kimse tekrar bakmaz. Bu asimetri, bir webhook payload değişikliğinin bir çağıranın aktif olarak istediği bir yanıt gövdesindeki aynı değişiklikten daha fazla dikkat hak etmesinin bütün nedenidir.</p> <h2>Bir webhook payload'unda gerçekte breaking change sayılan nedir?</h2> <table> <thead> <tr> <th>Değişiklik</th> <th>Çoğu alıcı için breaking mi</th> </tr> </thead> <tbody><tr> <td>Yeni bir alan eklemek</td> <td>Hayır, eğer alıcılar bilinmeyen alanları görmezden geliyorsa (bu varsayımı doğrulayın, kabul etmeyin)</td> </tr> <tr> <td>Bir alanı kaldırmak</td> <td>Evet, bir şey onu okuyorsa</td> </tr> <tr> <td>Bir alanı yeniden adlandırmak</td> <td>Evet, eskisini kaldırmakla işlevsel olarak aynı</td> </tr> <tr> <td>Bir alanın tipini değiştirmek (string'den objeye)</td> <td>Evet, neredeyse her zaman</td> </tr> <tr> <td>JSON gövdesindeki alanları yeniden sıralamak</td> <td>Hayır, anahtara göre parse eden herhangi bir alıcı için, ki hepsi böyle olmalı</td> </tr> <tr> <td>Event adını veya tipini değiştirmek</td> <td>Evet, alıcılar buna göre filtreliyor veya yönlendiriyorsa</td> </tr> </tbody></table> <p>"Bir alan eklemek güvenlidir" satırı ekiplerin en çok dayandığı ve varsaymak yerine doğrulamaya en değer olanıdır. İzin verici bir JSON parser'ı varsayılan olarak bilinmeyen alanları görmezden gelir, ama katı bir şemaya deserialize eden bir alıcı, birkaç tipli dil bunu ek yapılandırma olmadan yapar, beklenmedik bir alan belirdiği anda tüm payload'u reddedebilir. Bir alan eklemek webhook'unuz için ancak alıcıların nasıl parse ettiğini bildiğinizde güvenlidir, JSON'un kendisi izin verici olduğu için değil.</p> <h2>Bir webhook payload'u nasıl versiyonlanır?</h2> <p>Bir API yanıtına çok benzer, bir farkla: alıcı hiçbir zaman istek göndermez, bu yüzden bir sürüm isteyemez, ve sürümü gönderen belirtmek zorundadır. Bu, gövdede veya teslimatın kendisindeki bir istek başlığında olabilir; <a href="https://docs.github.com/en/webhooks/webhook-events-and-payloads">GitHub'ın teslimatları</a> <code>X-GitHub-Event</code> ve <code>X-GitHub-Hook-ID</code> taşır, ve <a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md">Standard Webhooks spesifikasyonu</a> meta verilerini <code>webhook-*</code> başlıklarına koyar. Payload'da bir sürüm alanı (<code>"payload_version": 2</code>) en ucuz seçenektir ve alıcılar buna göre dallanmaya istekliyse çalışır. Versiyonlu bir event tipi (<code>invoice.updated</code>, bir alıcının gönüllü olarak abone olduğu ayrı bir event olarak <code>invoice.updated.v2</code> olur) kurması daha fazla iş gerektirir ama eski şeklin hiç migrate etmeyenlere akmaya devam etmesi anlamına gelir, ki bu bir REST endpoint'ine göre burada daha önemlidir çünkü her alıcıyı arayıp güncellemesini isteyemezsiniz. Webhook endpoint'i kaydedilirken seçilen abonelik başına bir ayar, kararı her teslimde dallanmak yerine önden alır, ve zaten bir abonelik kaydınız varsa ona bağlanacak doğru seçimdir.</p> <pre><code>POST /alici-endpoint { "event": "invoice.updated", "payload_version": 2, "data": { "invoice_id": "inv_123", "status": "paid" } } </code></pre> <h2>Kimin dinlediğini bile nasıl bilirsiniz?</h2> <p>Bir API changelog'unda bu sorunun eşdeğerinden daha kötü, çünkü bir webhook'un sizin tarafınızda çağıranı adlandıran bir gelen istek günlüğü yoktur; sadece bir endpoint'in 200 aldığını söyleyen, gövdeyle ne yaptığını değil, kendi giden teslim günlüğünüz vardır. En azından iki şeyi takip edin: <a href="https://changeloop.dev/blog/tr/internal-api-changelog/">dahili API changelog'larının</a> dahili tüketiciler için önerdiği aynı disiplinle, sahibi olan her kayıtlı endpoint, ve bir payload değişikliğinden sonra endpoint başına teslim başarısızlık oranınız. Bir değişiklikten hemen sonra bir endpoint'ten gelen 4xx veya 5xx yanıtlardaki bir sıçrama, alacağınız bir stack trace'e en yakın şeydir, ve genellikle bir alıcının bozulduğuna dair tek sinyaldir, çünkü onu işleten ekip bunu günlerce fark etmeyebilir.</p> <h2>Webhook changelog'u API changelog'undan ayrı olmalı mı?</h2> <p>Aynı sayfada ayrı bir bölüm, ayrı bir yayın değil. <a href="https://changeloop.dev/blog/tr/api-changelog/">Bir API changelog'u</a> zaten kimin okuduğunu ve nasıl abone olunduğunu belirler; bir webhook payload değişikliği aynı akışa aittir, alıcı tarafındaki bir geliştiricinin "bu benim entegrasyonumu etkiliyor mu" diye tarayarak filtreleyebileceği kadar açık etiketlenmiş, çünkü bir webhook tüketicisinin genel bir API changelog'unu kontrol etmek için genellikle başka bir nedeni yoktur ve onu ancak biri doğrudan oraya yönlendirirse bulur.</p> <h2>Bir webhook payload'u için makul bir kullanımdan kaldırma penceresi nasıl görünmeli?</h2> <p>Eşdeğer REST kullanımdan kaldırmasından daha uzun, çünkü alıcı tarafındaki migrasyon genellikle doğrudan bağlantınız olmayabilecek ikinci bir ekibin bunu fark etmesi, planlaması ve kendi aciliyeti olmadan yayınlaması anlamına gelir. Bir ay, alıcının muhtemelen hâlâ izin verici bir kütüphaneyle parse ettiği bir alan için makul bir alt sınırdır; katı bir şemanın tamamen reddedeceği bir alan kaldırma için üç ay veya daha fazlası daha güvenlidir. Mümkünse pencere boyunca eski ve yeni şekli birlikte gönderin (eski <code>status</code> alanı ve onun sürüm 2'deki karşılığı aynı payload'da), çünkü eski alanı okuyan bir alıcı kodunu değiştirmeden çalışmaya devam eder, ve zaten migrate etmiş biri artık ihtiyaç duymadığı alanı sadece görmezden gelir.</p> <h2>FAQ</h2> <p><strong>Webhook tüketicileri yayınlanmadan önce bir payload değişikliğini onaylamak zorunda mı?</strong> Varsayılan olarak bir onay mekanizması yoktur, ve tam da bu yüzden kullanımdan kaldırma penceresi burada bir REST API'den daha önemlidir: kimse hazır olduğunu onaylamaz, bu yüzden pencere eski şekil kaybolmadan önce çoğu alıcının kendi zamanında migrate etmesine yetecek kadar uzun olmalı.</p> <p><strong>Bilinmeyen alanları uyarı olmadan eklemek hiç güvenli midir?</strong> Sadece alıcılarınızın izin verici parse ettiğini varsaymak yerine doğruladıktan sonra. Bir changelog kaydı az maliyetlidir ve tahmin unsurunu ortadan kaldırır; "JSON parser'ları extraları görmezden gelir" varsayımıyla sessizce alan eklemek katı deserialize eden herhangi bir alıcıyı bozar.</p> <p><strong>Bir payload değişikliğinden sonra bozuk bir webhook alıcısını tespit etmenin en hızlı yolu nedir?</strong> Değişiklikten hemen sonraki saatlerde izlenen, endpoint başına teslim başarısızlık oranı. Size ne bozulduğunu söylemez, sadece bir şeyin bozulduğunu, ama alacağınız en erken ve genellikle tek sinyaldir.</p> <p><strong>Yeniden deneme mantığı alıcıların bir payload değişikliğini atlatmasına yardımcı olur mu?</strong> Hayır. Bir yeniden deneme aynı yeni payload'u tekrar gönderir; alıcının parse edebileceği bir şekle dönmez. Bir payload değişikliği bir alıcıyı ilk teslimde ve sonraki her yeniden denemede aynı şekilde bozar.</p> </article> <article> <h1>API sunset header'ı: ne zaman gönderilir</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p><code>Sunset</code>, <a href="https://www.rfc-editor.org/rfc/rfc8594">RFC 8594</a>'te tanımlanan, bir çağırana bir kaynağın ne zaman yanıt vermeyi durduracağını söyleyen tek bir yanıt header'ıdır. <a href="https://changeloop.dev/blog/tr/api-deprecation/">API deprecation</a> tam duyur-hatırlat-brownout-emekliye ayır zaman çizelgesini ve onunla birlikte giden bildirimleri ele alır; bu yazı o zaman çizelgesindeki tek bir makine tarafından okunabilir sinyal hakkındadır, gerçekte ne söylediği hakkındadır, ve RFC'nin kendisinin onu göndermemeyi söylediği tek durum hakkındadır.</p> <h2>Sunset header'ı ne söyler, ne söylemez?</h2> <p>Kaynağın yanıt vermemesinin beklendiği noktayı, tek bir HTTP-date olarak taşır:</p> <pre><code>Sunset: Sat, 31 Dec 2028 23:59:59 GMT </code></pre> <p>RFC ona bir garanti değil bir ipucu der: kaynağın tam olarak o zaman damgasına kadar çalışmaya devam edeceğini vaat etmez, ve sonrasında başarısızlığın nasıl görüneceği hakkında hiçbir şey söylemez. Çağıranlar bir 4xx, bir yönlendirme, veya hiç yanıt alamayabilir; header ayrım yapmaz. Geçmişte kalan bir zaman damgası, değerdeki bir hata yerine "şimdi, veya herhangi bir an" anlamına gelir. Bunların hiçbiri protokol tarafından zorunlu kılınmaz. Header'ı hiç okumayan bir client tam olarak her zamanki gibi davranır, ve kaynağın gittiğini, zaten öğrenecek olduğu şekilde öğrenir.</p> <h2>Gerçekte ne zaman gönderilmeli?</h2> <p>Sadece kaynak gerçekten yanıt vermeyi durduracaksa, sadece artık önerilen seçim olmaktan çıktığında değil. RFC, deprecation'ın iki aşamada gerçekleştiğini açıkça belirtir, ve Sunset header alanı sadece ikincisine aittir: API, bir sürümün artık tercih edilmediğinin duyurulduğu birinci aşama boyunca tamamen çalışır durumda kalır, ve header alanı orada geçerli değildir. Sürüm gerçekten yanıt vermemesi planlandığında geçerli olur.</p> <p>Bu, deprecation zaman çizelgesine doğrudan denk gelir: <code>Deprecation</code> header'ı ilk günden, duyuru adımından itibaren gönderilir; <code>Sunset</code>, eski davranışın gerçekten duracağı tarihi tanımlar, ki bu <a href="https://changeloop.dev/blog/tr/api-deprecation/">dört adımlı zaman çizelgesinin</a> emekliye ayırma dediği aynı tarihtir. <code>Sunset</code>'i ilk gün göndermek yanlış değildir, çünkü tarih o zamana kadar zaten sabitlenmiştir, ama bir deprecation duyurmadan onu göndermek, veya gerçekten emekliye ayırmaya karar vermediğiniz bir sürüm için ayarlamak, çağıranlara henüz karar vermediğiniz bir şeyi söylemektir.</p> <h2>Caching ile etkileşir mi?</h2> <p>Hayır, ve RFC bunu doğrudan söyler: <code>Sunset</code> ve HTTP caching ilgisiz sorunları çözer ve üst üste binen değil tamamlayıcı olarak okunmalıdır. Caching header'ları önbelleğe alınmış bir kopyanın ne zaman yeniden kullanılmasının güvenli olduğunu söyler; <code>Sunset</code> kaynağın şu anki durumu hakkında hiçbir şey söylemez, sadece kaynağın kendisinin var olmayı bırakacağını söyler. Bir yanıt, sunset olduğu ana kadar tamamen cache'lenebilir olabilir. Birini diğerinin yerine kullanmayın, ve uzun bir <code>max-age</code>'in yaklaşan bir sunset tarihini iptal ettiğini, ya da tersini, varsaymayın.</p> <h2>Tek bir header birden fazla endpoint'i sunset yapabilir mi?</h2> <p>Header, onu döndüren kaynağa uygulanır, ama RFC bir servisin daha geniş bir kapsamı belgelemesine izin verir: bir API'nin ana kaynağındaki bir Sunset tarihi, sadece o tek URL'nin değil, tüm API'nin gittiği anlamına gelecek şekilde tanımlanabilir. Sorun şu ki bu sadece kapsam kuralınızı zaten bilen çağıranlar için işe yarar. Header'ı yüzeysel okuyan bir çağıran, istediği tek kaynakta bir sunset görür, başka hiçbir şey görmez, bu yüzden daha geniş bir kapsam, ima edilmek yerine çağıranın bulabileceği bir yere yazılmalıdır.</p> <h2>Header'ın yanında ne gönderilmeli?</h2> <p>Emekliye ayırmanın açıklandığı yere bir link. RFC 8594, tam olarak bunun için kendi <code>sunset</code> link ilişkisini kaydeder: header'ın çıplak zaman damgasından ayrı olarak, emekliye ayırma politikasını, yaklaşan tarihi, veya nasıl göç edileceğini açıklayan bir kaynağa işaret etmek için.</p> <pre><code>HTTP/1.1 200 OK Sunset: Sat, 31 Dec 2028 23:59:59 GMT Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>O linki kendi <a href="https://changeloop.dev/changelog-examples">changelog örneklerinize</a> veya özel bir migrasyon sayfasına yönlendirmek, neredeyse hiçbir client kodunun incelemediği bir header'ı, gerçekten bakan bir insanın anında bulduğu bir şeye dönüştürür. Onu <a href="https://changeloop.dev/blog/tr/api-deprecation/#which-headers-should-a-deprecated-endpoint-send">deprecation header'larından</a> <code>successor-version</code> ilişkisiyle birleştirin, ve bir çağıran sadece yanıttan hem nereye gideceğini hem de bunun yerine neyin geçtiğini alır.</p> <h2>Bu uçtan uca nasıl görünür?</h2> <p><code>v1</code>'in 1 Mart 2027'de gideceğini varsayalım. İlk gündeki deprecation duyurusu, <a href="https://changeloop.dev/blog/tr/api-deprecation/">deprecation header'larına</a> göre her <code>v1</code> yanıtına <code>Deprecation</code> ve <code>Link: rel="successor-version"</code> ekler, ama emekliye ayırma tarihi bir yer tutucu değil gerçekten sabitlenene kadar <code>Sunset</code>'i bekletir. Sabitlendiğinde, her <code>v1</code> yanıtı şunu taşır:</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>Bir çağıranın gateway'i veya izlemesi her iki header üzerinde de bağımsız olarak uyarı verebilir: <code>Deprecation</code> daha yeni bir sürümün var olduğunu söyler, <code>Sunset</code> bunun üzerinde bir saat olduğunu söyler. Hiçbir header 1 Mart'tan önce değişmek zorunda değildir; değişen şey, o gün ve önceden planlanmış herhangi bir brownout penceresi sırasında, yanıtın kendisidir.</p> <h2>Bir brownout header'ın söylediğini değiştirir mi?</h2> <p>Header değerinin kendisinin planlanmış bir brownout için değişmesine gerek yoktur: kaynak öncesinde aralıklı olarak başarısız olsa da olmasa da sunset tarihi hâlâ sunset tarihidir. Değişen şey header değil, yanıttır. <a href="https://changeloop.dev/blog/tr/api-deprecation/">API deprecation</a>'ın tarif ettiği gibi, duyurulan tarihten önceki haftalarda kısa <code>410 Gone</code> pencereleri planlamak, bir çağıranın başarısızlıkla ilk temasını, header'ın tarihi geldiği gün gerçek olan yerine bir prova haline getiren şeydir.</p> <h2>FAQ</h2> <p><strong>Gerçek HTTP client'ları veya araçları Sunset header'ını gerçekten okur mu?</strong> Client tarafında nadiren. Değeri çoğunlukla sizinle çağıran arasındaki altyapıyı işleten kişi içindir: header'ı izlemek için yapılandırdığınız bir API gateway'i veya bir izleme aracı, çağıranın kodu hiç fark etmeden çok önce kendi ekibinizi, veya bir ortağınkini, uyarabilir. Bunu, karşı tarafın zaten sahip olduğunu varsayabileceğiniz bir şey değil, etrafında araç inşa ettiğiniz bir sinyal olarak ele alın.</p> <p><strong><code>Sunset</code>, <code>Cache-Control: max-age</code> ile aynı şey mi?</strong> Hayır. <code>max-age</code>, önbelleğe alınmış bir kopyanın ne kadar süre geçerli kaldığıyla ilgilidir; <code>Sunset</code>, kaynağın ne zaman tamamen var olmayı bırakacağıyla ilgilidir. Bir yanıt kısa bir <code>max-age</code> ve yıllar sonrasına ait bir <code>Sunset</code> tarihi taşıyabilir, ya da tersi, ve hiçbir header diğerini kısıtlamaz.</p> <p><strong>Tüm endpoint için değil, giden tek bir alan için Sunset gönderebilir miyim?</strong> Hayır, header kaynağa, yani URL'ye kapsamlıdır, yanıt gövdesi içindeki bir alana değil. Endpoint'in kendisi ayakta kalırken giden bir alan, parametre veya enum değeri için bunun yerine <code>Deprecation</code> header'ını ve bir changelog girdisini kullanın; <a href="https://changeloop.dev/blog/tr/api-deprecation/">API deprecation</a> tam olarak bu tür bir değişikliği duyurmayı ele alır.</p> <p><strong>Sunset tarihinin değişmesi gerekirse ne olur?</strong> Header değerini güncelleyin ve bunu ilk başta duyuran changelog girdisinde belirtin; yayımlanmış bir tarihi sessizce değiştirmek, bir çağıranın hiçbir tarihinizin gerçek olmadığına karar vermesine yol açan şeydir. RFC değeri tam olarak tarihlerin bazen değiştiği için bir ipucu olarak çerçeveler, ama açıklama olmadan değişen bir tarih bir sonrakine de mal olur.</p> </article> <article> <h1>API changelog: neyi yayınlamalı, kim okur</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Bir API changelog'u, bir çağıranın fark edebileceği her değişikliğin tarihli kaydıdır; onu yayınlayan ekip için değil, API'ye entegre olan kişiler için yazılır. Bu kitle, onu bir ürün changelog'undan farklı bir belge yapar: okuyucu, kodunun gelecek ay hala çalışıp çalışmayacağına karar veriyordur. Çoğu aynı şekilde başarısız olur, dahili bir release akışının filtrelenmiş bir kopyası olarak; kaldırılan bir alan, bir metin düzeltmesiyle aynı ağırlıkta yan yana durur ve ikisi de okunmaz.</p> <h2>API changelog nedir?</h2> <p>Başka insanların kod yazdığı bir arayüzdeki değişikliklerin herkese açık, tarihli günlüğüdür. Bir şeyin oraya ait olup olmadığına dair yararlı test, değişikliğin dahili olarak ne kadar büyük olduğuyla hiç ilgili değildir. Geçen yıl yazılmış ve o zamandan beri hiç dokunulmamış, doğru bir çağıranın bu yüzden farklı davranıp davranmayacağını sorar. Bu test bazı çok küçük değişiklikleri kabul eder ve bazı çok büyükleri dışlar.</p> <p>Aşağıdaki her şey çağıranın şirket dışında olduğunu ve bu belge dışında pratikte ulaşılamaz olduğunu varsayar. Çağıran aynı şirketten başka bir ekip olduğunda, hesap kendi ele alışını hak edecek kadar değişir; <a href="https://changeloop.dev/blog/tr/internal-api-changelog/">dahili API changelog'ları</a> bu kitlenin yerine neye ihtiyaç duyduğunu ele alır.</p> <table> <thead> <tr> <th>Belge</th> <th>Kitle</th> <th>Yanıtladığı</th> </tr> </thead> <tbody><tr> <td>API changelog</td> <td>API'yi çağıran geliştiriciler</td> <td>Entegrasyonum hala çalışıyor mu?</td> </tr> <tr> <td>Sürüm notları</td> <td>Ürünün kullanıcıları</td> <td>Şimdi yapamadığım neyi yapabilirim?</td> </tr> <tr> <td>Deprecation bildirimi</td> <td>Belirli bir şeyin çağıranları</td> <td>Bu ne zaman çalışmayı bırakacak?</td> </tr> <tr> <td>Durum sayfası</td> <td>Şu an etkilenen herkes</td> <td>Şu anda çalışmıyor mu?</td> </tr> <tr> <td>Geçiş kılavuzu</td> <td>Yükseltme yapan çağıranlar</td> <td>A'dan B'ye nasıl geçerim?</td> </tr> </tbody></table> <p><a href="https://changeloop.dev/blog/tr/api-migration-guide/">API geçiş kılavuzu nasıl yazılır</a> bu son belgeyi baştan sona ele alır; kısacası, uyumsuz değişiklik girişinin onu değiştirmeye çalışmak yerine bağlantı vermesi gereken şey budur.</p> <p>Beşi ayrı ömürleri olan ayrı belgelerdir. Bir deprecation bildirimi tarihli bir sözdür ve changelog'a da aittir, ama bir changelog kaydı bir kez yazılır, deprecation ise sunset'ine kadar takip edilir. Bunları birleştirmek, sunset'lerin kaçırılmasının nedenidir.</p> <h2>Tek bir kayda ne girer?</h2> <p>Altı şey, ilk üçü genellikle eksik olanlardır. Değişikliğin kendisi, dahili bileşen yerine istek veya yanıt cinsinden ifade edilmiş. Doğru bir çağıranı bozup bozmadığı. Çağıranın ne yapması gerektiği, "hiçbir şey" dahil. Yürürlüğe girdiği tarih. Etkilenen sürüm veya sürümler. Varsa geçiş kılavuzuna bir bağlantı.</p> <p>"Accounts endpoint'i iyileştirildi" diyen bir kayıt altısında da başarısız olur. "<code>accounts.type</code> alanı artık daha önce <code>personal</code> döndürdüğü yerde <code>individual</code> döndürüyor; 2 Eylül'den önce oluşturulan hesaplar için mevcut değerler değişmedi; stringi karşılaştırmadığınız sürece işlem gerekmiyor" diyen bir kayıt, altısını da tek cümlede yanıtlar.</p> <p>Kayıtları departmana göre değil, sonuca göre kategorize edin. Neredeyse tüm değeri üç etiket taşır: breaking, additive ve fixed. <a href="https://semver.org/">Semantic Versioning</a> ilk ikisini zaten kesin şekilde tanımlar, ve kendi tanımlarınızı icat etmek yerine onunkileri ödünç almak, semver bilen bir okuyucunun etiketlerinizi bilmesi anlamına gelir. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> isterseniz daha uzun bir set sunar, ve merkezi kuralı burada başka her yerden daha güçlü geçerlidir: günlük insanlar içindir, ve bir commit başlığı dökümü değildir.</p> <h2>Bir API changelog'u sürüm notlarından nasıl farklıdır?</h2> <p>Sürüm notları ürünün artık ne yapabildiğini anlatır. Bir API changelog'u sözleşmenin artık ne olduğunu anlatır. Aynı yayınlanan iş genellikle her ikisinde de bir kayıt üretir, farklı ifade edilmiş, çünkü kitleler farklı şeylere ihtiyaç duyar: yeni bir dışa aktarma formatı bir kullanıcı için bir özellik, o alana göre dallanan bir çağıran için ise yeni bir enum değeridir.</p> <p>Pratik sonuç, ikisinin farklı stille aynı akış olamayacağıdır. Yayınladığınız her şeye abone olan bir çağıran sonunda abonelikten çıkacak, ve sonra breaking change'i kaçıracaktır. Tek bir akış yayınlıyorsanız filtreleyin; ikisini yayınlıyorsanız API olanını daraltın ve içine asla bir pazarlama kaydı girmesine izin vermeyin. İki formu yan yana <a href="https://changeloop.dev/blog/tr/changelog-vs-release-notes/">changelog vs sürüm notları</a> içinde karşılaştırıyoruz.</p> <h2>Bir API changelog'u nerede yaşamalı?</h2> <p>Referans dokümantasyonunun yanında, kararlı bir URL'de, her kayıt bir fragment veya kendi yoluyla ayrı ayrı adreslenebilir şekilde. Çağıranlar olay incelemelerinde ve dahili biletlerde kayıtlara bağlantı verir, ve bağlanamayan bir kayıt yerine ekran görüntüsü olarak yapıştırılır.</p> <p>Bir sayfa olarak da, makine tarafından okunabilir çıktı olarak da yayınlayın. Kayıtlar yapılandırılmış veri haline geldiğinde bir <a href="https://www.jsonfeed.org/version/1.1/">JSON Feed spesifikasyonu</a>'nu izleyen bir JSON akışı ya da bir <a href="https://www.rssboard.org/rss-specification">RSS akışı</a> hiçbir şeye mal olmaz, ve bu, bir müşterinin değişikliklerinizi kendi release sürecine dahil etmesini sağlayan şeydir. Bu ayrıca birinin üzerine bir şey inşa edip etmeyeceğini belirleyen kısımdır. GitHub, <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">REST API sürümlerini</a> aynı nedenle referansın hemen yanında belgeler: sürüm politikası arayüzün bir parçasıdır.</p> <h2>Pratikte iyi bir kayıt nasıl görünür?</h2> <p>Aynı haftadan, yukarıda anlatılan şekilde üç kayıt:</p> <pre><code>2026-09-02 Breaking v2 `POST /invoices` artık müşterinin hesap para birimiyle eşleşmeyen bir `currency`'i reddediyor, sessizce dönüştürmek yerine 422 döndürüyor. Dönüştürmeye güvenen çağıranlar hesap para birimini göndermeli. Sadece v2'yi etkiler; v1, 2027-01-15'teki sunset'ine kadar değişmez. 2026-09-02 Additive v1, v2 `Invoice`, fatura ödenene kadar null olan bir `settled_at` zaman damgası kazanıyor. İşlem gerekmiyor. Bilinmeyen alanları reddeden client'lar güncellenmeli. 2026-08-31 Fixed v2 `GET /invoices?status=`, bilinmeyen bir durum için 400 yerine boş bir sayfa döndürüyordu. Artık kabul edilen değerlerle 400 döndürüyor. Yazım hatası yapan çağıranlar daha önce sıfır sonuç görüyordu, şimdi bir hata görüyor. </code></pre> <p>Üçüncüsü en sık atlanan türdür, çünkü dahili olarak bir hata düzeltmesidir. O boş sayfanın etrafına bir retry kuran bir çağıran için bu bir davranış değişikliğidir, ve kayıt destek biletini önleyen şeydir. Etiket fixed diyor ve gövde bir çağıranın fark edebileceği şeyi söylüyor, ki bu her düzeltmeyi bir breaking change'e şişirmeden günlüğü dürüst tutan ayrımdır.</p> <h2>Çağıranlar buna nasıl abone olur?</h2> <p>Onlara birden fazla kanal verin, çünkü farklı işleri var. Her şeyi isteyen geliştirici için bir akış. Sadece breaking change isteyen kişi için e-posta. Kodun kendisi için yanıt başlıkları, hiç kontrol etmeyi unutmayan tek abone: <a href="https://datatracker.ietf.org/doc/html/rfc8594">RFC 8594'te tanımlanan <code>Sunset</code> başlığı</a>, emeklilik tarihini bir client kütüphanesinin loglayabileceği yanıta koyar.</p> <p>Çoğu ekibin atladığı kanal doğrudan olandır. Geçen hafta değiştirdiğiniz alanı bir çağıran kullandıysa, kim olduğunu bilirsiniz, ve o hesaplara bir e-posta herhangi bir yayından daha değerlidir. Bu, kimsenin talep etmediği bir değişikliğe uygulanan <a href="https://changeloop.dev/blog/tr/customer-feedback-loop/">müşteri geri bildirim döngüsünü kapatma</a> ile aynı disiplindir: etkilenen kişilere ayrı ayrı söylenir, geri kalan herkes akışı alır. Bir webhook, güvenmeden önce bilinmesi gereken kendi başarısızlık moduna sahip dördüncü bir kanaldır: <a href="https://changeloop.dev/blog/tr/webhook-changelog/">webhook changelog'ları</a> orada bir payload değişikliğinin, yeni şekli reddedecek bir çağıran olmadan neden sessizce bozulduğunu ele alır.</p> <h2>Bir breaking change için kayıt nasıl yazılır?</h2> <p>Nedenle değil, bozulmayla başlayın. On kaydı tarayan bir çağıranın, bunun ona iş çıkarıp çıkarmayacağını ilk cümlede bilmesi gerekir. Sonra tarih, etkilenen sürümler, geçiş, ve eski davranış değişmek yerine kayboluyorsa son tarih.</p> <p>Aynı içeriği deprecation bildirimine, yanıt başlığına ve doğrudan e-postaya, tutarlı ifade edilmiş şekilde koyun, ve dördüne de aynı tarihi verin. Aralarındaki sapma, planlanmış bir değişikliği bir olaya dönüştüren hatadır, çünkü sadece birini okuyan çağıran yanlış tarihe göre hareket eder. <a href="https://changeloop.dev/blog/tr/breaking-changes/">Breaking change nedir</a> kararın kendisini kapsar, ve <a href="https://changeloop.dev/blog/tr/api-deprecation/">bir API nasıl deprecate edilir</a> sonrasındaki takvimi kapsar.</p> <p>changeloop'ta, bir API değişikliği pull request birleştirildiğinde bir kayda dönüşür, bir kişi taslağı düzenler ve onaylar, ve kayıt, widget geri bildirimi pull request'in kapattığı GitHub issue'suna dönüşen bir çağırana o issue üzerinden bildirildiği anda <a href="https://changeloop.dev/docs">akış ve widget</a> üzerinde yayınlanır. Burada önemli olan gözden geçirme adımıdır: bir API changelog'u sözleşmeye dayalı bir belgedir, ve hiçbir taslak bir kişi okumadan bir çağırana ulaşmamalıdır.</p> <h2>FAQ</h2> <p><strong>Her API değişikliği bir changelog kaydına ihtiyaç duyar mı?</strong> Doğru bir çağıranın fark edebileceği her değişiklik evet, dahili saydıklarınız dahil. İstek veya yanıt üzerinde gözlemlenebilir etkisi olmayan değişiklikler hayır, ve onları eklemek okuyucuları gözden geçirmeye alıştırır.</p> <p><strong>API changelog'u dokümanlarda mı, pazarlama sitesinde mi yaşamalı?</strong> Dokümanlarda, referansın hemen yanında. Okuyucu genellikle zaten oradadır, ve pazarlama sitesindeki bir changelog, onun için yazılmamış bir kitle kazanma eğilimindedir.</p> <p><strong>Ne kadar geriye gitmeli?</strong> Süresiz. Kayıtlar yıllar sonra olay incelemelerinde alıntılanır, ve budanmış bir günlük o bağlantıları bozar. Budamak yerine sayfalayın.</p> <p><strong>Her API sürümü için ayrı bir changelog gerekir mi?</strong> Hayır, kayıt başına bir sürüm alanı olan tek bir günlük okumak ve aramak daha kolaydır. Sürüme göre filtreleme sayfanın bir özelliğidir, belgeyi bölmek için bir sebep değil.</p> </article> <article> <h1>İnsanların takip ettiği bir changelog sayfası nasıl kurulur</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Bir changelog sayfası, biri ona geri dönecekse kurmaya değer. Bu, sadece ona sahip olmaktan daha yüksek bir çıta, ve çoğunun düştüğü çıta budur: var olan, footer'da bağlantısı verilen, sıçramalarla güncellenen ve bir olay sırasında dışında kimsenin ziyaret etmediği bir sayfa. İkisini ayıran kararlar hiçbir şey yazılmadan önce verilir, ve çoğunlukla sayfanın nerede yaşadığı ve aynı içerikten başka ne üretildiği hakkındadır.</p> <h2>Changelog sayfası nedir?</h2> <p>Bir üründe neyin değiştiğinin, size ait bir URL'de herkese açık, tarihli listesidir. Aynı kayıtların görünebileceği beş yüzeyden biridir, ve yararlı soru hangisini seçeceğiniz değil, hangisinin kanonik olduğu ve hangilerinin ondan üretildiğidir.</p> <table> <thead> <tr> <th>Yüzey</th> <th>En iyi olduğu</th> <th>Maliyet</th> </tr> </thead> <tbody><tr> <td>Barındırılan sayfa</td> <td>Arama, bağlantı, uzun kayıt</td> <td>Bir URL ve bir şablon</td> </tr> <tr> <td>Uygulama içi widget</td> <td>Sayfayı hiç ziyaret etmeyen kullanıcılara ulaşmak</td> <td>Bir embed, ve ölçülülük</td> </tr> <tr> <td>Doküman bölümü</td> <td>API ve geliştirici kitlesi</td> <td>Referansın yanında tutmak</td> </tr> <tr> <td>JSON akışı</td> <td>Değişikliklerinizin üzerine inşa eden müşteriler</td> <td>Zaten sahip olduğunuz yapı</td> </tr> <tr> <td>RSS akışı</td> <td>Bir kez abone olan geliştiriciler</td> <td>Neredeyse hiçbir şey</td> </tr> </tbody></table> <p>Kanonik bir kaynak seçin, bir kez yayınlayın, ve gerisini üretin. Sayfayı ve widget'ı ayrı ayrı elle sürdüren ekipler, uyuşmayan iki metinle sonuçlanır, ve uyumsuzluğu bir müşteri keşfeder.</p> <h2>Bir changelog sayfası nerede yaşamalı?</h2> <p>Kendi domaininizde, kararlı bir yolda, her kayıt bir fragment veya kendi yoluyla ayrı ayrı adreslenebilir şekilde. Üç yaygın yerleşim bir ana site yolu, bir alt domain, ve dokümantasyonun bir bölümüdür. Ana sitedeki bir yol, lehine değil aleyhine tartışılması gereken varsayılan seçimdir: sitenin otoritesini devralır, ekstra sertifika veya DNS gerektirmez, ve sayfayı diğer her şeyle aynı navigasyonda tutar.</p> <p>Bir alt domain, sayfa pazarlama sitesinden farklı bir sistem tarafından sunulduğunda ve aksi halde proxy yapıyor olacağınızda doğru cevaptır. Bedeli, otoriteyi ayrı biriktirmesidir. Changelog'u dokümanlara koymak, kitle geliştiricilerse doğrudur, <a href="https://changeloop.dev/blog/tr/api-changelog/">API changelog</a>'da ele alınan nedenle: okuyucu genellikle zaten oradadır.</p> <p>Seçimden daha önemli olan, kayıtların ayrı ayrı bağlanabilir olmasıdır. İnsanlar olay incelemelerinde ve dahili biletlerde kayıtlara bağlantı verir, ve sadece "changelog, aşağı kaydır" olarak bağlanabilen bir kayıt yerine ekran görüntüsü olarak yapıştırılır.</p> <h2>Bir changelog sayfası neye ihtiyaç duyar?</h2> <p>Beş şey, ve ilk ikisinde çoğu sayfa başarısız olur. Değişiklik başına tarihli bir kayıt, en yeni önce. İlgilenilen türü taramak için kayıt başına bir kategori veya etiket. Kayıt başına bir permalink. Bir abonelik yolu. Elli civarı kayıttan sonra bir arama veya filtre.</p> <p>Gerisi opsiyoneldir. Ekran görüntüleri yardımcı olur ve bakım maliyeti çıkarır. Yazar isimleri bazı ürünlerde güven inşa eder, bazılarında gürültü çıkarır. Sürüm numaraları bir API'nin çağıranları için önemlidir, neredeyse başka hiç kimse için değil. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a>, kendinizinkini icat etmek için sebebiniz yoksa etiketler için makul bir varsayılan sunar, ve merkezi kuralı, gerisini atsanız bile saklamaya değer olandır: günlük insanlar içindir.</p> <p>Ürününüz sürekli yayınlıyorsa sürüme göre değil tarihe göre gruplayın. "Bu, dokuzuncu gündeki olayımızdan önce mi sonra mı" diye tarayan bir okuyucu bir tarih arar, ve sürüm numarasına göre düzenlenmiş bir sayfa onu hesap yapmaya zorlar.</p> <h2>Sayfa mı, uygulama içi widget mı?</h2> <p>İkisi de, tek bir kaynaktan. Sayfa aramanın, bağlantıların ve uzun kaydın yaşadığı yerdir. Widget, sayfayı hiç ziyaret etmeyecek çoğunluğa ulaşma yolunuzdur, ve çalışır çünkü zaten kullandıkları üründe görünür.</p> <p>Widget'ın başarısızlığı kesintidir. Her kayıt için dikkat isteyen bir rozet bir hafta içinde kalıcı olarak reddedilir, ki bu size gerçekten önemli olan kayıt için kanalı kaybettirir. Okuyucunun son baktığından beri okunmamışları sayın, ilk ziyarette sayacı sessizce başlatın ki kimse bir yıllık geçmişin rozetiyle karşılanmasın, ve okuyucunun onu kendisi için açmak yerine kendi açmasına izin verin.</p> <h2>Bir changelog sayfası nasıl makine tarafından okunabilir hale getirilir?</h2> <p>Aynı kayıtları akış olarak da yayınlayın. Bir <a href="https://www.jsonfeed.org/version/1.1/">JSON akışı</a>, onu kodda tüketen herhangi biri için en düşük sürtünmeli seçenektir, ve bir <a href="https://www.rssboard.org/rss-specification">RSS akışı</a>, bir okuyucuda abone olan bir geliştiricinin beklediği şeydir. Kayıtlar elle yazılmış HTML yerine yapılandırılmış veri olduğunda ikisi de az maliyetlidir, ki bu kanonik kopyayı yapılandırılmış tutmanın gerçek gerekçesidir.</p> <p>Sayfayı işaretleyin de. Kayıtlar tarihi ve başlığı olan eserlerdir, ve <a href="https://schema.org/CreativeWork">schema.org</a> kelime dağarcığını sağlar. Permalink'lerle aynı nedenle değerlidir: sayfayı bir tarayıcı olmayan şeyler tarafından, müşterinin kendi release süreci dahil, kullanılabilir hale getirir. Bunların hiçbiri, altta yatan kayıtlar en başından beri hiç yapılandırılmış veri olmadıysa çalışmaz; <a href="https://changeloop.dev/blog/tr/changelog-file-formats/">changelog dosya formatları</a>, bu akışın ve bu işaretlemenin gerçekte üretildiği doğruluk kaynağı olarak Markdown, JSON ve YAML'in her birinin neye mal olduğunu ele alır.</p> <h2>Bir changelog sayfası SEO'ya yardımcı olur mu?</h2> <p>Dolaylı ve yavaş şekilde. Tek tek kayıtlar nadiren sıralanır, çünkü kimsenin yazmadığı bir sorguyu hedeflemezler. Sayfa yerini bağlantılar yoluyla kazanır: kayıtlar destek yanıtlarında, forumlarda ve olay analizlerinde alıntılanır, ve o bağlantılar size ait bir URL'de birikir. İki yıl boyunca haftalık güncellenen bir sayfa, ait olduğu ürün için de güvenilir bir tazelik sinyalidir.</p> <p>İşe yaramayan şey, kayıtları içerik pazarlaması gibi ele almaktır. Uzunluk için üç paragrafa şişirilmiş bir kayıt, gerçek işinde daha kötüdür, ki bu iş bir okuyucuya kullandığı bir şeyin değişip değişmediğini tek cümlede söylemektir. Changelog'un aramayı desteklemesini istiyorsanız, çabayı permalink'lere, akışa ve ona giden dahili bağlantılara koyun, ve kayıtları kısa tutun. Kendi <a href="https://changeloop.dev/changelog-examples">changelog örnekleri</a> sayfamız bu dengeyi doğru yakalayan sayfaları toplar.</p> <h2>İnsanlar nasıl abone olur?</h2> <p>Onlara zaten kullandıkları yolları verin: geliştiriciler için bir RSS veya JSON akışı, sadece önemli olanları duymak isteyenler için e-posta, ve ikisini de asla yapmayacak herkes için uygulama içi widget. Varsaymak yerine ne duymak istediklerini sorun, çünkü breaking change isteyen ve metin düzeltmeleri alan bir okuyucu ikisinden de abonelikten çıkar.</p> <p>En son eklenecek yol döngüyü kapatan yoldur. Bir kayıt belirli bir kişinin talep ettiği şeyi çözdüğünde, sayfayı okumasını ummak yerine bunu ona doğrudan söyleyin. changeloop'ta kayıt aynı anda <a href="https://changeloop.dev/docs">sayfa, akış ve widget</a> üzerinde yayınlanır, ve widget geri bildirimi pull request'in kapattığı GitHub issue'suna dönüşen kişi o issue'da kayda bağlantıyla bilgilendirilir ve kaydı widget'ta görür. Mekanik herhangi bir abonelikle aynıdır; fark, alıcının zaten sormuş olmasıdır. Bu, <a href="https://changeloop.dev/blog/tr/customer-feedback-loop/">geri bildirim döngüsünü changelog tarafından kapatma</a>'da detaylandırılan argümandır.</p> <h2>FAQ</h2> <p><strong>Changelog sayfası bir alt domainde mi, bir yolda mı olmalı?</strong> Varsayılan olarak ana sitedeki bir yol, çünkü sitenin otoritesini devralır ve ekstra altyapı gerektirmez. Farklı bir sistem sayfayı sunduğunda bir alt domain haklı çıkar.</p> <p><strong>Sayfa aynı anda kaç kayıt göstermeli?</strong> Bir ekranı doldurmaya yeter kadar ve daha fazlası değil, ardından sayfalama. Bir belgeye iki yıllık geçmiş yüklemek yavaştır ve en yeni kaydı bulmayı zorlaştırır.</p> <p><strong>Eski kayıtlar hiç silinmeli mi?</strong> Hayır. Sitenizin dışından alıntılanırlar ve bağlantılar bozulur. Bir kaydı yerinde bir notla düzeltin, ve URL'yi canlı tutun.</p> <p><strong>Sayfada her değişiklik görünmeli mi?</strong> Sadece bir kullanıcının fark edebileceği olanlar. Dahili refactor'ları kaydeden bir sayfa okuyucuları gözden geçirmeye alıştırır, ve gözden geçirilen bir sayfa acil bir şey taşıdığı gün başarısız olur.</p> </article> <article> <h1>Okunan ürün güncellemesi e-posta şablonu</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Okunan ürün güncellemesi e-postası, tam olarak duyurduğu şeyi talep eden birine gönderilmiş olandır. Gerisi, gelen kutusunun kalanıyla ilginçlik açısından rekabet eder, çoğu hafta bir release duyurusunun kaybettiği bir rekabet. Bu tek gerçek, herhangi bir ifadeden önce e-postanın şeklini belirlemelidir: onu kim alıyor, ve o kişi listeye girmek için ne yaptı.</p> <h2>Ürün güncellemesi e-postası nedir?</h2> <p>Mevcut kullanıcılara zaten kullandıkları bir üründe neyin değiştiğini söyleyen bir mesajdır. Dört ayrı türü vardır, ve onları tek bir liste olarak ele almak, açılma oranlarının düşmesinin nedenidir. Her birinin farklı bir tetikleyicisi, farklı bir kitlesi ve farklı bir kabul edilebilir sıklığı vardır.</p> <table> <thead> <tr> <th>Tür</th> <th>Tetikleyici</th> <th>Kitle</th> <th>Sıklık</th> </tr> </thead> <tbody><tr> <td>Hedeflenmiş bildirim</td> <td>Birinin belirli talebi yayınlandı</td> <td>Bir kişi</td> <td>Her olduğunda</td> </tr> <tr> <td>Breaking change bildirimi</td> <td>Okuyucuya iş çıkaran bir değişiklik</td> <td>Sadece etkilenen hesaplar</td> <td>Her olduğunda</td> </tr> <tr> <td>Özet</td> <td>Zamanın geçmesi</td> <td>Opt-in kullanıcılar</td> <td>En fazla aylık</td> </tr> <tr> <td>Lansman duyurusu</td> <td>Kesintiye değer bir lansman</td> <td>Segment veya herkes</td> <td>Nadir, ve nadir hissettirmeli</td> </tr> </tbody></table> <p>Çoğu ekip sadece üçüncüsünü kurar, herkese gönderir, ve ürün güncellemesi e-postalarının işe yaramadığı sonucuna varır. İlk ikisi neredeyse tüm değeri taşır, çünkü okuyucunun önceden bir ilgilenme nedeni vardır, ve mesaj o neden canlıyken gelir.</p> <p>Buradaki dört satırın hepsi müşteriler için yazılmıştır. Satış, destek ve customer success de neyin gönderildiğini bilmeli, genelde bu dördünden farklı bir biçimde; <a href="https://changeloop.dev/blog/tr/internal-release-notes/">dahili release notları</a> bu belgenin ne söylemesi gerektiğini ve müşteriye yönelik notdan önce neden çıkması gerektiğini ele alır.</p> <p>E-posta, bir lansman duyurusunun kullanabileceği birkaç kanaldan yalnızca biridir. <a href="https://changeloop.dev/blog/tr/new-feature-announcement/">Yeni bir özellik nasıl duyurulur</a> diğerlerini ve özelliğin gerçek büyüklüğüne göre aralarında nasıl seçim yapılacağını ele alır.</p> <h2>Şablona ne girer?</h2> <p>Bu sırayla altı blok. İlki genellikle eksik olan ve işi yapan bloktur.</p> <pre><code>Konu: <ne değişti, okuyucunun kelimeleriyle> 1. Bunu neden alıyorsunuz "Mart'ta CSV dışa aktarma istediniz." veya "Entegrasyonunuz 15 Ocak'ta değişecek olan /v1/invoices'ı çağırıyor." 2. Ne değişti Bir cümle. Artık ne mümkün, veya artık ne bozuluyor. 3. Ne yapmanız gerekiyor Genellikle "hiçbir şey". Bunu üstü kapalı bırakmak yerine açıkça söyleyin. 4. Nerede görülür Ana sayfaya değil, changelog kaydına bir bağlantı. 5. Ne zaman Yayınlandığı tarih, veya ne zamandan beri geçerli olduğu. 6. Nasıl abonelikten çıkılır Bir tık, ve hemen saygı gösterilen. </code></pre> <p>Blok 1, bir mesaj ile genel bir yayın arasındaki farktır. İlk satırda, bunun kişisel olarak talep ettiği bir şeyin çözümü olduğu söylenen bir okuyucu gerisini okur. Onsuz, 2'den 5'e kadar olan bloklar ne kadar iyi yazılmış olursa olsun bir bültendir.</p> <p>Bütünü yaklaşık 150 kelimenin altında tutun. E-posta, changelog kaydına bir işaretçidir, ve detayın ait olduğu yer kayıttır. Kaydın tamamını yeniden üreten bir e-posta, okuyucuya tıklamak için bir sebep vermez, size de kimseyi ilgilendirip ilgilendirmediğine dair bir sinyal vermez.</p> <h2>Hangi konu satırları işe yarar?</h2> <p>Değişikliği isimlendirin, release'i değil. "CSV dışa aktarma yayında" "Eylül güncellemesi"ni yener, çünkü ilki okuyucunun değerlendirebileceği bir gerçek, ikincisi ise bir kapsayıcıdır. Konu satırındaki sürüm numaraları bir API'nin çağıranları için yararlıdır ve herkes için gürültüdür, bu da kitleleri ayırmak için başka bir sebeptir.</p> <p>Okuyucunun onay vermediği bir fayda iddia etmekten kaçının. "Raporlarınız artık daha hızlı" onun deneyimi hakkında bir şey iddia eder; "10.000 satırın üzerindeki raporlar artık bir saniyeden az sürede yükleniyor" bir değişikliği bildirir ve önemli olup olmadığına karar vermesini ona bırakır.</p> <h2>Ne zaman ve kime gönderilmeli?</h2> <p>Hedeflenmiş bir bildirimi şey yayınlandığı anda, isteyen kişilere, ayrı ayrı gönderin. Bir breaking change bildirimini tarih kesinleşir kesinleşmez ve ona yakın bir kez daha, tüm listeye değil gerçekten etkilenen hesaplara gönderin. Bir özeti sadece bir okuyucunun aksi halde bir şeyi kaçıracağı kadar değişikliğiniz varsa gönderin, ve insanların ayrı ayrı kaydolmasına izin verin.</p> <p>Neredeyse hiç kullanmamanız gereken liste "tüm kullanıcılar"dır. Belirli bir mesajı genel bir mesaja dönüştürür, ve abonelikten çıkmayı öğretir. Zaten depoladığınız davranışa göre segmentleyin: kim istedi, kim bu endpoint'i kullanıyor, kim bu planda.</p> <h2>Göndermek için onay gerekli mi?</h2> <p>Mevcut müşteriler için, kullandıkları bir hizmetle ilgili bir güncelleme genellikle bir potansiyel müşteriye pazarlamadan farklı bir hukuki sorudur, ve cevap nerede olduklarına ve kayıt olurken onlara ne söylediğinize bağlıdır. AB'de ilgili soru <a href="https://gdpr-info.eu/art-6-gdpr/">GDPR'nin 6. maddesi</a> kapsamında hangi yasal dayanağın geçerli olduğudur, ve ABD'de ticari mesajlar <a href="https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business">FTC'nin CAN-SPAM uyum kılavuzunda</a> belirtilen özel gereksinimler taşır. İkisi de pratikte aynı şeyi ister: kim olduğunuzu söyleyin, amacı netleştirin, ve insanların durdurabilmesine izin verin.</p> <p>Dayanak ne olursa olsun, işlemsel ve pazarlama akışlarını gönderim düzeyinde ayrı tutun. Bir müşterinin promosyonel bir özetle aynı listeyi paylaştığı için abonelikten çıktığı bir breaking change bildirimi, tarihini bekleyen bir destek olayıdır.</p> <h2>Doldurulmuş nasıl görünür?</h2> <p>Hedeflenmiş bildirim, en değerli ürün güncellemesi e-postası ve çoğu ekibin hiç kurmadığı:</p> <pre><code>Konu: CSV dışa aktarma yayında Merhaba Dana, Mart'ta CSV dışa aktarma istemiştin. Bu sabah yayına girdi. Raporların artık mevcut görünümün CSV'sini üreten bir Dışa Aktar düğmesi var, filtreler dahil. Senin tarafında yapman gereken bir şey yok. Hesabında zaten açık. Detaylar: example.com/changelog#csv-export Yayınlandı: 2 Eylül 2026 Bunu talep ettiğin için alıyorsun. Talep güncellemelerinden çık: <bağlantı> </code></pre> <p>Doksan kelime, ve okuyucu ilk satırda bunun neden geldiğini biliyor. Bunu, dokuz maddeden biri olarak göründüğü ve Dana'nın kendi talebinin gittiğini fark etmesi için hiçbir sebebi olmadığı aylık bir özetteki aynı değişiklikle karşılaştırın.</p> <h2>Ne ölçülmeli?</h2> <p>Sadece açılma oranı değil. Hedeflenmiş bir bildirim için soru, talep eden kişinin geri gelip şeyi kullanıp kullanmadığıdır, dolayısıyla izlenmesi gereken sayı, kayda tıklama ve o hesabın özelliği bir hafta içinde kullanıp kullanmadığıdır. Bir breaking change bildirimi için bu kapsamdır: etkilenen hesapların yüzde kaçı tarihten önce açtı, ve kiminle bireysel takip yaptınız.</p> <p>Bir özet, dördü arasında açılma oranının bir şey ifade ettiği tek türdür, ve orada bile bir sektör kıyaslamasına karşı olmaktan çok kendi geçmişine karşı bir eğilim olarak daha kullanışlıdır. Farklı ürün güncellemesi e-postası türlerinin farklı işleri vardır, dolayısıyla hepsi üzerinden ortalanmış bir rakam, üzerinde hareket edilebilecek hiçbir şeyi tanımlamaz.</p> <h2>Sürüm notlarından nasıl farklı?</h2> <p>Sürüm notları erişilebilir kalan bir belgedir. E-posta bir kez gerçekleşen bir teslimat mekanizmasıdır. Aynı değişiklik ikisini de üretir, ve e-posta işaret ettiği kayıttan daha kısa olmalıdır. <a href="https://changeloop.dev/blog/tr/release-notes-best-practices/">Sürüm notları en iyi uygulamalar</a> belgeyi kapsar, ve <a href="https://changeloop.dev/blog/tr/changelog-vs-release-notes/">changelog vs sürüm notları</a> hangisini yazdığınızı kapsar.</p> <p>Doğru kurulması gereken ilişki şu: changelog kaydı kanonik metindir ve e-posta onu alıntılar. Bu ikisi ayrıştığında, tıklayan okuyucu değişikliğin farklı bir tanımını bulur ve ikisine de güvenmeyi bırakır. Önce kaydı yayınlamak ve e-postayı ondan üretmek sapmayı yapı gereği ortadan kaldırır. changeloop da kendi tarafında aynı şekilde çalışır: bir kayıt bir kez gözden geçirilir ve <a href="https://changeloop.dev/docs">sayfa, akış ve widget</a> üzerinde yayınlanır, ve onu widget aracılığıyla isteyen kişi, geri bildiriminin dönüştüğü GitHub issue'sunda ve widget'ın kendisinde bilgilendirilir. changeloop e-postayı göndermez; e-posta aracınız yayınlanan kaydı alıntılar.</p> <h2>FAQ</h2> <p><strong>Bir ürün güncellemesi e-postası ne sıklıkla çıkmalı?</strong> Alıcının bilmek istediği belirli bir şey olduğu kadar sık, ki bu hedeflenmiş bir bildirim için talebi yayınlandığında her seferinde, bir özet için en fazla aylık demektir.</p> <p><strong>E-posta changelog kaydının tamamını içermeli mi?</strong> Hayır. Bir cümle ve bir bağlantı. Kayıt kanonik versiyondur, ve e-postadaki tam bir kopya, uyumlu tutulması gereken iki metin anlamına gelir.</p> <p><strong>Ne açılma oranı beklemeliyim?</strong> Her türü bir kıyaslamaya karşı değil kendisine karşı karşılaştırın. Hedeflenmiş bir bildirim ve aylık bir özet farklı ürünlerdir, ve onları ortalamak üzerinde hareket edilmeye değer tek rakamı gizler.</p> <p><strong>Breaking change'ler için ayrı bir liste gerekli mi?</strong> Evet, ve insanların sonucunu anlamadan gelişigüzel abonelikten çıkamayacağı liste bu olmalı, çünkü onlara bir kesintiye mal olan liste budur.</p> </article> <article> <h1>Geliştiricileri kaybetmeden bir API nasıl deprecate edilir</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Bir API'yi deprecate etmek, bir şeyin bugün hâlâ çalıştığını ve belirtilen bir tarihte çalışmayı durduracağını duyurmak, sonra o sözün her iki yarısını da tutmaktır. Çoğu deprecation ikinci yarıda başarısız olur: tarih sessizce kayar, veya gelir ve bildirimi hiç görmemiş çağıranlar bunu bir hatadan öğrenir. Bir deprecation, etkilenen her çağıran ya göç ettiğinde ya da bireysel olarak göç etmediği söylendiğinde tamamlanmıştır.</p> <h2>API deprecation nedir?</h2> <p>Deprecation, bir endpoint'in, alanın veya versiyonun gitmekte olduğunu duyurmakla onu gerçekten kaldırmak arasındaki dönemdir. Bu dönem boyunca eski davranış çalışmaya devam eder, dokümantasyon gittiğini söyler, ve her yanıt makine tarafından okunabilir bir uyarı taşır. Kaldırma, genellikle sunset olarak adlandırılan ayrı, daha sonraki olaydır. İkisi karıştırılır, ve bu karışıklık hasarın gerçekleştiği yerdir: "deprecated" "belki zaten gitmiştir" anlamına gelmeye başlar, ve çağıranlar her iki kelimeye de güvenmeyi bırakır.</p> <table> <thead> <tr> <th>Terim</th> <th>Anlam</th> <th>Çağıranların güvenebileceği şey</th> </tr> </thead> <tbody><tr> <td>Deprecated</td> <td>Gitmek üzere olarak duyuruldu, hâlâ çalışıyor</td> <td>Sunset tarihine kadar tam davranış</td> </tr> <tr> <td>Sunset</td> <td>Çalışmayı durdurduğu tarih</td> <td>Bu tarihten sonra hiçbir şey</td> </tr> <tr> <td>Retired / kaldırıldı</td> <td>Gitti; istekler başarısız olur</td> <td>İdeal olarak yerine geçeni adlandıran bir hata</td> </tr> <tr> <td>Legacy</td> <td>Tanımsız. Kelimeden kaçının</td> <td>Hiçbir şey, ki bu sorundur</td> </tr> </tbody></table> <h2>Bir deprecation dönemi ne kadar sürmeli?</h2> <p>Bir çağıranın öğrenip işi yapmasına yetecek kadar uzun, bunu yazdığınız andan değil bildirimin ona ulaştığı andan itibaren ölçülerek. Doksan gün, genel bir web API'si için yaygın taban çizgisidir. On iki ay, son kullanıcıların yüklediği yazılıma gömülü herhangi bir şey için normaldir, çünkü düzeltme onların sürüm sürecinden de geçmelidir. Google'ın versiyonlama kılavuzu <a href="https://google.aip.dev/185">AIP-185</a>, makul bir geçiş süresi ister ve beta işlevselliğini kaldırmadan önce bile 180 gün önerir, ve Kubernetes <a href="https://kubernetes.io/docs/reference/using-api/deprecation-policy/">deprecation politikasını</a> aylar yerine sürüm sayısı olarak belgeler, ki bu çağıranlarınız sürüme göre güncellediğinde doğru birimdir.</p> <p>Bir dönem seçin, onu politika olarak yazın, ve değişiklik başına karar vermeyi bırakın. Yayımlanmış bir politika, her deprecation'ı bir müzakereden bir kuralın uygulanmasına dönüştürür.</p> <p>Deprecation politikasını yazmak pencerenin başını kapsar; <a href="https://changeloop.dev/blog/tr/sunsetting-api-version/">bir API sürümünü kapatmak</a> dönem gerçekten bittiğinde ve sürüm çalışmayı bıraktığında sonunda gereken ayrı bildirimi kapsar.</p> <h2>Deprecation zaman çizelgesi</h2> <p>Birinci günde birlikte duyurulan dört tarih. Her biri geldiğinde ayrı bir changelog girdisidir, bu yüzden hikaye sadece changelog'u okuyanlara dört kez anlatılır.</p> <ol> <li><strong>Duyurun.</strong> Girdi neyin deprecate edildiğini, nedenini, neyin yerine geçtiğini, ve sunset tarihini söyler. Eski şeyin dokümantasyonu göçe bağlanan bir banner kazanır. Yanıtlar aşağıda açıklanan başlıkları kazanır.</li> <li><strong>Hatırlatın, yarı yolda.</strong> İkinci bir girdi, ve eski davranışı hâlâ kullanan her çağırana doğrudan bir mesaj. Bu, kullanım verisine ihtiyaç duyan adımdır: deprecate edilmiş endpoint'i hâlâ kimin çağırdığını listeleyemiyorsanız, bunu yapamazsınız, ve bir sonraki deprecation'dan önce düzeltmeye değer.</li> <li><strong>Tarihten kısa süre önce brownout yapın.</strong> Eski davranış için kısa bir pencere boyunca, bir saat veya bir gün, hatalar döndürün, sonra geri yükleyin. Her bildirimi kaçıran çağıranlar hâlâ zaman varken şimdi öğrenir. GitHub, <a href="https://github.blog/2020-07-30-token-authentication-requirements-for-api-and-git-operations/">API için şifre kimlik doğrulamasını emekliye ayırmadan</a> önce planlanmış brownout'lar kullandı, ve bu listede en etkili tek adımdır.</li> <li><strong>Sunset.</strong> Kaldırın. Yerine geçen hata, yerine geçeni adlandırır ve göç kılavuzuna bağlanır. Hatayı uzun süre yerinde tutun; bir 404 bir çağırana hiçbir şey söylemez.</li> </ol> <h2>Bir deprecation bildirimi ne söylemeli?</h2> <p>Bir deprecation bildirimi, neyin gittiğini, ne zaman durduğunu, yerine ne kullanılacağını, ve kimin etkilendiğini söyler. İşte şekli, doldurulmuş:</p> <blockquote> <p><strong><code>GET /v1/reports/daily</code> deprecate edildi ve 1 Mart 2027'de çalışmayı durduracak.</strong> Aynı verileri stabil bir şema ve sayfalama ile döndüren <code>GET /v2/reports?granularity=day</code> ile değiştiriliyor. Son 30 günde v1 endpoint'ini çağıran 214 entegrasyonu etkiler; sizinki de bunlardan biriyse, bu bildirimi e-posta ile de alacaksınız. Göç kılavuzu: [link]. 1 Mart 2027'ye kadar hiçbir şey değişmiyor. O tarihten itibaren v1 endpoint'i bu girdiye bir bağlantı ile <code>410 Gone</code> döndürüyor.</p> </blockquote> <p>Her cümle okuyucunun ihtiyaç duyduğu bir şey taşır. Etkilenen entegrasyonların sayısı her okuyucuya okumaya devam edip etmeyeceğini söyler. "Kadar hiçbir şey değişmiyor" etkilenmeyenlerin sekmeyi kapatmasına izin veren cümledir. <a href="https://changeloop.dev/changelog-examples">Changelog örnekleri</a> sayfası bu şekli tutarlı bir şekilde yazan ekiplerin girdilerini toplar, ve ilk kendinizinkini yazmadan önce üçünü okumaya değer.</p> <h2>Deprecate edilmiş bir endpoint hangi başlıkları göndermeli?</h2> <p>Duyuru gününden itibaren deprecate edilmiş endpoint'ten gelen her yanıtta halefe <code>Deprecation</code>, <code>Sunset</code> ve bir <code>Link</code> gönderin. <a href="https://datatracker.ietf.org/doc/html/rfc9745"><code>Deprecation</code> başlığı</a> deprecation'ın yürürlüğe girdiği tarihi taşır; <a href="https://datatracker.ietf.org/doc/html/rfc8594"><code>Sunset</code> başlığı</a> endpoint'in yanıt vermeyi durduğu tarihi taşır; <code>Link: <url>; rel="successor-version"</code> yerine ne kullanılacağını gösterir.</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/changelog/daily-reports>; rel="deprecation" </code></pre> <p>Çoğu çağıran başlıkları asla kendisi okumayacaktır. Değerleri, bir çağıranın HTTP istemcisinin, gateway'inin veya izlemesinin okuyabilmesidir, ki bu deprecation'ınızı sizin tarafınızda bir sayfa yerine onların tarafında bir uyarıya dönüştürür. Gönderdiğiniz SDK'lar birini gördüğünde bir uyarı kaydetmelidir.</p> <h2>Kime bildirildi, ve bunu nasıl biliyorsunuz?</h2> <p>Bu, sunset'in sakin mi yoksa bir destek olayı mı olacağına karar veren adımdır, ve sadece bir changelog ile yapılması en zor olanıdır. Bir changelog girdisi, changelog'u okuyan herkesi bilgilendirir. Bir deprecation, kodu başarısız olacak belirli insanlara ulaşmalıdır, ve onları bulmanın olağan yolu yarı yolda hatırlatmanın ihtiyaç duyduğu aynı kullanım verisidir: deprecate edilmiş davranışı yakın zamanda çağıran API anahtarları, uygulamalar veya hesaplar.</p> <p>Çalıştırdığımız döngü: girdi, deprecation'ı ekleyen pull request'ten hazırlanır, bir insan ifadeyi ve tarihi gözden geçirir, ve yayımlandığında girdinin kendisi bildirimdir. Sorunla ilgili widget geri bildirimi veya yerine geçen için talebi, pull request'in kapattığı bir GitHub issue'suna dönüşen herkes, o issue'da gönderildiğini söyleyen ve girdiye bağlantı veren bir yorum alır. <a href="https://changeloop.dev/docs">Feed ve widget</a> aynı girdiyi diğer herkese sunar, <a href="https://changeloop.dev/blog/tr/api-changelog/">API changelog</a>'daki her diğer girdiyle birlikte. Yapmadığımız şey, bir insan onu yayımlamadan önce deprecation'ın "gönderildi" olmasına izin vermektir; yanlış tarihli bir bildirim, bildirim olmamasından daha kötüdür.</p> <p>Aracınız ne olursa olsun, sunset gününde cevaplayabilmeniz gereken soru şudur: geçen hafta bunu hâlâ hangi çağıranlar kullanıyordu, ve hangilerine doğrudan söyledik? Cevap "bunun hakkında paylaşım yaptık" ise, sunset hazır değildir.</p> <h2>Deprecate etmek ile versiyonlamak arasındaki fark nedir?</h2> <p>Versiyonlamak, yeni olan varken eski davranışı nasıl kullanılabilir tuttuğunuzdur; deprecation, eskiyi nasıl emekliye ayırdığınızdır. Öncekinin deprecation politikası olmadan yeni bir API versiyonu, ikisini de sonsuza kadar çalıştırmaya bir taahhüttür. Versiyonlama olmadan bir deprecation, gecikmeli bir <a href="https://changeloop.dev/blog/tr/breaking-changes/">breaking change</a>'dir. İkisine de ihtiyacınız var, ve versiyon daha kolay olan yarıdır. GraphQL, adlandırmaya değer istisnadır: genellikle artırılacak hiçbir versiyon numarası yoktur, ve <a href="https://changeloop.dev/blog/tr/graphql-schema-deprecation/">GraphQL şema deprecation'ı</a>, paylaşılan tek bir şemanın bunun yerine bir direktifle bir alanı nasıl emekliye ayırdığını ele alır.</p> <h2>FAQ</h2> <p><strong>Deprecate edilmiş bir endpoint tam olarak öncekiyle aynı şekilde çalışmaya devam etmeli mi?</strong> Evet, sunset tarihine kadar. İzin verilen tek değişiklikler eklenen başlıklardır ve sona doğru, önceden duyurduğunuz planlı bir brownout'tur.</p> <p><strong>Emekliye ayrılmış bir endpoint hangi durum kodunu döndürmeli?</strong> <code>410 Gone</code>, yerine geçen ve changelog girdisine işaret eden bir <code>Link</code> başlığı ve bir gövde ile. <code>404</code>, URL'nin hiç var olmadığını söyler, ki bu yanlış ve yardımcı olmayan bir şeydir.</p> <p><strong>Bir deprecation dönemi kısaltılabilir mi?</strong> Sadece güvenlik için. Eski davranış istismar edilebilirse, bunu söyleyin, dönemi kısaltın, ve changelog'a güvenmek yerine etkilenen her çağırana doğrudan söyleyin.</p> <p><strong>Bir alanı mı yoksa sadece tüm endpoint'leri mi deprecate etmem gerekiyor?</strong> Alanlar, parametreler, enum değerleri, varsayılanlar ve başlıkların hepsi aynı muameleye ihtiyaç duyar, çünkü her biri doğru bir çağıranı bozabilir. Kaldırılmış bir alan en yaygın deprecation türüdür ve en sık atlanan olanıdır.</p> </article> <article> <h1>Çağıranlar için API versiyonlama en iyi uygulamaları</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>API versiyonlama, onu değiştirdikten sonra eski bir sözleşmeyi çalışır tutma pratiğidir, böylece çağıranlar sizin değil kendi programlarına göre ilerleyebilir. O cümle önemli olan iki kararı içerir: sözleşmeyi değiştirmenin ne sayıldığı, ve eskisinin ne kadar süre çalışmaya devam ettiği. Versiyon numarasının nerede yaşadığı, ki çoğu versiyonlama tartışması bununla ilgilidir, üçünün en az önemlisidir ve doğru yapılması en kolay olanıdır.</p> <h2>Bir API ne zaman versiyonlanmalı?</h2> <p>Bir API'yi sadece bir değişiklik doğru bir çağıranı bozacaksa versiyonlayın. Ekleme değişiklikleri, yeni alanlar, yeni endpoint'ler, yeni isteğe bağlı parametreler, bir versiyona ihtiyaç duymaz; eski sözleşmeye yazılmış çağıranlar çalışmaya devam eder ve yeni yetenek basitçe oradadır. Bir <a href="https://changeloop.dev/blog/tr/breaking-changes/">breaking change</a> buna ihtiyaç duyar, çünkü alternatif bir çağıranın bunu bir hatadan öğrenmesidir. Ekleme olanlar dahil her sürümü versiyonlamak, çağıranlara versiyonların gürültü olduğunu öğretir, ve önemli bildirimleri okumayı bırakırlar.</p> <p>Pratik test, breaking change makalesindekiyle aynıdır: sadece dokümante edilmiş davranışa güvenen bir çağıran çalışmaya devam etmek için bir şeyi değiştirmek zorundaysa, değişiklik bir versiyona ihtiyaç duyar. Değilse, mevcut versiyon altında gönderin ve bir changelog girdisi yazın.</p> <h2>Hangi API versiyonlama şeması kullanılmalı?</h2> <p>Çağıranlarınızın en kolay görüp ayarlayabileceği şemayı kullanın, ki bu çoğu genel API için URL yolunda bir versiyon veya tarihli bir versiyon başlığıdır. Dört yaygın şema, yetenekten çok çağırandan ne istediklerinde farklılık gösterir, ve seçim için doğru temel budur.</p> <table> <thead> <tr> <th>Şema</th> <th>Örnek</th> <th>Çağıranın yapması gereken</th> <th>Kim kullanıyor</th> </tr> </thead> <tbody><tr> <td>URL yolu</td> <td><code>/v2/invoices</code></td> <td>Göç ederken URL'yi değiştirmek</td> <td>Çoğu genel REST API'si</td> </tr> <tr> <td>Versiyon başlığı</td> <td><code>X-GitHub-Api-Version: 2022-11-28</code></td> <td>Bir başlık göndermek, veya varsayılanı kabul etmek</td> <td>GitHub</td> </tr> <tr> <td>Tarihli hesap versiyonu</td> <td><code>Stripe-Version: 2026-08-26</code></td> <td>İstek başına veya hesap başına bir tarih sabitlemek</td> <td>Stripe</td> </tr> <tr> <td>Sorgu parametresi</td> <td><code>/invoices?version=2</code></td> <td>Bir parametre eklemek</td> <td>Daha eski API'ler; şimdi nadiren seçiliyor</td> </tr> <tr> <td>Medya türü</td> <td><code>Accept: application/vnd.example.v2+json</code></td> <td>İçerik türlerini müzakere etmek</td> <td>Purist'ler; az çağıran yönetebiliyor</td> </tr> </tbody></table> <p><strong>URL yolu</strong> en görünür ve en az esnek olanıdır. Her çağıran bir log satırı okuyarak hangi versiyonda olduğunu görebilir, ve bir versiyon sıçraması bul-değiştir'dir. Maliyeti: tüm yüzey birden hareket eder, hepsi için yeni bir versiyon basmadan tek bir endpoint'in sözleşmesini değiştiremezsiniz, bu yüzden yol versiyonları nadir ve büyük olma eğilimindedir.</p> <p><strong>Versiyon başlığı</strong>, URL'leri stabil tutar ve hiçbir şey göndermeyen çağıranlar için sunucunun bir varsayılan seçmesine izin verir, <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">GitHub'ın REST API versiyonlaması</a> şöyle çalışır: <code>X-GitHub-Api-Version</code> içinde tarihle adlandırılmış bir versiyon, versiyonsuz çağıranların bozulmaması için varsayılan olarak en eski desteklenen versiyonla. Maliyeti: versiyon bir URL'de görünmezdir ve yeni bir istemcide unutulması kolaydır.</p> <p><strong>Tarihli hesap versiyonu</strong>, bir ekleme yapılmış başlık şemasıdır: versiyon hesaba karşı saklanır, böylece her istek hiçbir şey göndermeden onu alır. <a href="https://docs.stripe.com/api/versioning">Stripe'ın API versiyonlaması</a> her hesabı oluşturulduğu versiyona sabitler ve bir isteğin bunu <code>Stripe-Version</code> ile geçersiz kılmasına izin verir. Bu, çağıran için en dostça şemadır ve çalıştırması en çok iş gerektirendir, çünkü sunucu her desteklenen versiyon ile şu anki arasında çeviri yapmak zorundadır.</p> <p><strong>Sorgu parametresi</strong> ve <strong>medya türü</strong>, her ikisi de çalışır ve ikisi de görünürlük testini farklı şekillerde başarısız olur: bir sorgu parametresi bir URL oluştururken kolayca düşer, ve bir medya türü versiyonu, bir çağıranın hata ayıklamak için kullandığı hemen hemen her araç için görünmezdir. Stripe'ın tarih tabanlı şeması tarih yaklaşımının en bilinen örneğidir ve <a href="https://changeloop.dev/blog/tr/stripe-api-versioning/">Stripe API'sini nasıl versiyonluyor</a> onu adım adım anlatır.</p> <h2>API versiyonlama pratikte nasıl yapılır?</h2> <p>Pratikte bir versiyon, adlandırılmış bir davranış kümesidir, ve sunucu her isteği bunlardan birine eşler. Adımlar, ismi hangi şema taşırsa taşısın aynıdır.</p> <ol> <li><strong>Versiyonları semantik versiyona değil, tarihe veya tam sayıya göre adlandırın.</strong> Bir web API'si bir paket değildir. Çağıranlar bir URL'nin minor versiyonunu sabitleyemez, bu yüzden <code>v2</code> veya <code>2026-08-26</code> bir çağıranın ihtiyaç duyduğu her şeyi söyler, ve <a href="https://semver.org/">semantik versiyonlama</a> şemanın yerine getiremeyeceği bir uyumluluk sözü ima eder.</li> <li><strong>Versiyonu umursamayan kod yollarının dışında tutun.</strong> Bir versiyon, iş mantığını dallandırmak yerine kenarda bir çeviri katmanı seçmelidir. Kod tabanının iki tam kopyası, bir versiyonun nasıl bakımsız kaldığıdır.</li> <li><strong>Her versiyona bir varsayılan ve bir doküman verin.</strong> Versiyon göndermeyen çağıranlar, sabitlenmemiş bir istemcinin sürüm günü bozulmaması için en yeniyi değil en eski desteklenen olanı alır. Her versiyonun öncekinden ne değiştiğini söyleyen bir sayfası vardır.</li> <li><strong>Bir destek penceresi belirleyin ve yayımlayın.</strong> Google'ın versiyonlama kılavuzu <a href="https://google.aip.dev/185">AIP-185</a>, makul ve iyi duyurulmuş bir geçiş süresi ister ve beta işlevselliği için bile 180 gün önerir. Bir pencere seçin, yazın, ve versiyon başına yeniden müzakere etmeden uygulayın.</li> <li><strong>Versiyonları endpoint'leri emekliye ayırdığınız gibi emekliye ayırın.</strong> Penceresini geçmiş bir versiyon, herhangi bir <a href="https://changeloop.dev/blog/tr/api-deprecation/">deprecate edilmiş API</a> ile aynı muameleyi görür: bir duyuru, her yanıtta bir <code>Sunset</code> başlığı (<a href="https://datatracker.ietf.org/doc/html/rfc8594">RFC 8594</a>), kalan çağıranlara yarı yolda bir hatırlatma, ve tutan bir kaldırma tarihi.</li> </ol> <h2>Bir REST API'sinde v1 ve v2 nedir?</h2> <p><code>v1</code> ve <code>v2</code>, aynı sunucunun aynı anda desteklediği iki sözleşme için isimlerdir. Bir <code>v2</code>, <code>v1</code>'deki bir şey çağıranlarını bozmadan değiştirilemediği için vardır, bu yüzden değişiklik yeni bir sözleşmeye gitti ve eskisi çalışmaya devam etti. Numaralar <code>v2</code>nin tamamlandığını veya <code>v1</code>'in öldüğünü ima etmez; ikisi de sadece dokümantasyon öyle söylüyorsa doğrudur. Her çeyrekte görünen bir <code>v3</code>, ekleme değişikliklerin versiyonlandığının, veya sözleşmenin hiçbir zaman değişikliği emmek için tasarlanmadığının bir işaretidir. gRPC aynı sorunu farklı bir şekilde çözer: <a href="https://changeloop.dev/blog/tr/grpc-protobuf-api-changes/">gRPC ve Protobuf API değişiklikleri</a> versiyonlamayı bir URL yolu yerine bir <code>.proto</code> dosyasındaki paket adı üzerinden ele alır, ve bir alanı yeniden adlandırmanın ücretsiz ama yeniden numaralandırmanın hiçbir REST çağıranının riskli olarak tanımayacağı bir breaking change olduğu bir wire formatını.</p> <h2>Bir versiyon değişikliği ne duyurmalı?</h2> <p>Bir versiyon değişikliği, neyin bozulduğunu, kimi etkilediğini, nasıl göç edileceğini, ve önceki versiyonun ne kadar süre çalışmaya devam ettiğini duyurmalıdır. Girdi, herhangi bir başka breaking change girdisiyle aynı şekle sahiptir, artı destek penceresini belirten bir satır. İşte başlıkla versiyonlanan bir API için bir tane:</p> <blockquote> <p><strong>API versiyon 2026-11-01 mevcuttur. Versiyon 2025-06-15, 1 Kasım 2027'ye kadar destekleniyor.</strong> 2026-11-01'de yeni: <code>GET /invoices</code>, <code>amount</code>'ı ondalık string yerine en küçük birimlerde tam sayı olarak döndürüyor, ve deprecate edilmiş <code>customer_name</code> alanı <code>customer</code> nesnesi lehine kaldırılıyor. 2025-06-15'te <code>amount</code>'ı string olarak parse eden çağıranları etkiler, ki bu Haziran 2025'ten önce oluşturulmuş sabitlenmemiş istemciler için varsayılandır. Göç: <code>amount</code>'ı tam sayı olarak parse edin ve ismi <code>customer.name</code>'den okuyun. Hazır olduğunuzda <code>X-Api-Version: 2026-11-01</code>'i sabitleyin. Versiyon sabitlemeyen çağıranlar için hiçbir şey değişmiyor.</p> </blockquote> <p>Son cümle, çoğu okuyucunun okumayı bırakmasına izin veren cümledir, ve her versiyon duyurusuna aittir. <a href="https://changeloop.dev/changelog-examples">Changelog örnekleri</a> sayfası böyle versiyonlayan API'lerden girdiler içerir, ve iyi olanlar ile geri kalanı arasındaki fark çoğunlukla o son cümledir.</p> <h2>Bir versiyon değiştiğinde kime bildirilir?</h2> <p>Eski versiyondaki herkese, bireysel olarak, ve diğer herkes için changelog'a. Bir versiyon değişikliği, "bunun hakkında paylaşım yaptık"ın kesinlikle önemli olan çağıranları kaçırdığı tek durumdur: iki yıl önce bir versiyon sabitleyip o zamandan beri bir sürüm notu okumamış olanlar. Kullanım verisi kim olduklarına cevap verir; bildirim onlara kodlarının olduğu yerde, yanıt başlıklarında ve hesap sahibine bir mesajda ulaşmalıdır.</p> <p>Çalıştırdığımız döngüde, bir versiyonu duyuran girdi, onu gönderen pull request'ten hazırlanır, bir insan tarafından incelenir, ve versiyonlu bir istemcinin JSON olarak okuyabileceği <a href="https://changeloop.dev/docs">feed ve widget</a>'e yayımlanır. Widget geri bildirimi değişikliği isteyen veya çözdüğü hatayı bildiren ve pull request'in kapattığı bir GitHub issue'suna dönüşen herkes, girdi yayına girdiğinde o issue'da bilgilendirilir. Mekanizma herhangi bir girdiyle aynıdır; bir versiyon sıçraması sadece en yüksek riski olan girdidir.</p> <h2>FAQ</h2> <p><strong>Her API değişikliği yeni bir versiyon almalı mı?</strong> Hayır. Sadece breaking change'ler. Ekleme değişiklikleri, bir changelog girdisiyle mevcut versiyon altında gönderilir. Ekleme değişikliklerini versiyonlamak, çağıranları versiyonları görmezden gelmeye eğitir.</p> <p><strong>URL versiyonlama mı yoksa başlık versiyonlaması mı daha iyi?</strong> URL versiyonlaması, çağıranlar için görmesi daha kolaydır ve sizin için parça parça geliştirmesi daha zordur; başlık versiyonlaması bunun tersidir. Çok sayıda küçük istemcisi olan genel bir API için, URL versiyonlaması daha az başarısız olur. Çeviri katmanı olan büyük bir API için, tarihli başlık versiyonu daha iyi ölçeklenir.</p> <p><strong>Aynı anda kaç versiyon desteklenmeli?</strong> Destek pencerenizin izin verdiği kadar az, ve asla sınırsız bir sayı değil. İki veya üç eşzamanlı versiyon normaldir; bundan fazlası genellikle versiyonların emekliye ayrılmadığı anlamına gelir.</p> <p><strong>Versiyonsuz istekler ne almalı?</strong> En eski desteklenen versiyon, böylece mevcut sabitlenmemiş istemciler çalışmaya devam eder, hangi versiyonu aldıklarını onlara söyleyen bir yanıt başlığıyla.</p> </article> <article> <h1>Breaking change: ne sayılır ve nasıl gönderilir</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Bir breaking change, doğru yazılmış bir çağıranın hayatta kalamayacağı bir değişikliktir. Tanım önemlidir çünkü bir şeyin "sayılıp sayılmadığı" hakkındaki çoğu tartışma gerçekte kimin onu yanlış tuttuğu hakkındadır. Bir çağıran dokümanınızı takip ettiyse ve değişikliğiniz kodunun çalışmasını durdurduysa, değişiklik breaking'ti. Ne amaçladığınızın bununla hiçbir ilgisi yoktur.</p> <p>Tüm test budur. Bu makalenin geri kalanı ondan çıkan şeydir: neyin testi geçemediği, neyin geçtiği, bir başarısızlığı merge edilmeden önce nasıl yakalayacağınız, ve bir tane gönderdiğinizi bildiğinizde ne yapmanız gerektiği.</p> <h2>Ne bir breaking change sayılır?</h2> <p>Testi çağırana uygulayın, diff'e değil. Sadece dokümante edilmiş davranışa güvenen bir çağıranın çalışmaya devam etmek için kodunu, yapılandırmasını veya verisini değiştirmesi gerektiğinde bir değişiklik breaking'tir. Bir alanı kaldırmak, bir endpoint'i yeniden adlandırmak, doğrulamayı sıkılaştırmak, bir varsayılanı değiştirmek ve bir değerin türünü değiştirmek hepsi buna uyar. İsteğe bağlı bir alan eklemek uymaz. Bir hatayı düzeltmek genellikle uymaz, aşağıda önemli bir istisna ile.</p> <table> <thead> <tr> <th>Değişiklik</th> <th>Breaking mi?</th> <th>Neden</th> </tr> </thead> <tbody><tr> <td>Bir alanı, endpoint'i, flag'i veya seçeneği kaldırmak veya yeniden adlandırmak</td> <td>Evet</td> <td>Doğru çağıranlar ona referans verir</td> </tr> <tr> <td>İsteğe bağlı bir alan veya yeni bir endpoint eklemek</td> <td>Hayır</td> <td>Mevcut çağrılar değişmez</td> </tr> <tr> <td>İsteğe bağlı bir girdiyi zorunlu yapmak</td> <td>Evet</td> <td>Onu atlayan çağrılar artık başarısız olur</td> </tr> <tr> <td>Daha önce kabul edilen doğrulamayı sıkılaştırmak</td> <td>Evet</td> <td>Çalışan girdiler artık reddedilir</td> </tr> <tr> <td>Bir varsayılan değeri değiştirmek</td> <td>Evet</td> <td>Onu ayarlamayan çağıranlar yeni davranış alır</td> </tr> <tr> <td>Bir türü değiştirmek (string'den sayıya, tek değerden dizeye)</td> <td>Evet</td> <td>Dokümante edilen türe yazılmış parser'lar başarısız olur</td> </tr> <tr> <td>Bir nesnenin anahtarlarını yeniden sıralamak</td> <td>Hayır</td> <td>Sırayı dokümante etmediyseniz</td> </tr> <tr> <td>Çağıranların dayandığı bir hatayı düzeltmek</td> <td>Pratikte evet</td> <td>Kazara sözleşmeler bölümüne bakın</td> </tr> <tr> <td>Bir hız sınırını veya boyut üst sınırını yükseltmek</td> <td>Hayır</td> <td>Çalışan hiçbir şey çalışmayı durdurmaz</td> </tr> <tr> <td>Bir hız sınırını veya boyut üst sınırını düşürmek</td> <td>Evet</td> <td>İyi olan trafik artık kısıtlanır</td> </tr> <tr> <td>Bir hata mesajının ifadesini değiştirmek</td> <td>Değişir</td> <td>Dokümante ettiyseniz veya çağıranlar buna göre eşleştiriyorsa breaking</td> </tr> </tbody></table> <h2>Ne breaking change sayılmaz?</h2> <p>Bir değişiklik, daha önce çalışan her çağrı değişmeden çalışmaya devam ediyor ve aynı anlama geliyorsa breaking değildir. Yeni bir endpoint eklemek, isteğe bağlı bir istek parametresi eklemek, yanıta bir alan eklemek, zorunlu bir girdiyi isteğe bağlı yapmak, bir sınırı yükseltmek ve kimsenin eşleştirmediği bir hata mesajını iyileştirmek testi geçer. Bu eklemeli değişiklikler sıradan bir changelog girdisiyle bir minor sürümde gönderilebilir.</p> <p>Eklemeli değişiklikler yine de üç durumda çağıranları bozar. Deserializer'ı bilinmeyen alanları reddeden bir istemci ilk yeni yanıt alanında başarısız olur, bu yüzden çağıranların tanımadıkları alanları yok saymaları gerektiğini erkenden dokümante edin. Yeni bir enum değeri, kapsamlı bir switch'e sahip her çağıranı bozar (aşağıda daha fazlası var). Ve büyüyen bir yanıt, bir çağıranı hiç düşünmek zorunda kalmadığı bir boyut sınırının, zaman aşımının veya sütun genişliğinin ötesine itebilir.</p> <p>Tablodaki dört satır daha yakından bakmayı hak ediyor, çünkü anlaşmazlıklar orada olur.</p> <h2>Ekiplerin kaçırdığı dört breaking change</h2> <p><strong>Kazara sözleşmeler.</strong> API'niz üç yıl boyunca aynı dokümante edilmemiş alanı döndürdüyse, bir çağıran onun üzerine inşa etmiştir. <a href="https://www.hyrumslaw.com/">Hyrum'un Kanunu</a> kısa versiyondur: yeterince kullanıcıyla, sisteminizin gözlemlenebilir her davranışına biri bağımlı olacaktır. Bu yüzden "bu bir hata düzeltmesiydi" bir savunma değildir. Düzeltme doğru olabilir ve yine de breaking olabilir. Onu öyle gönderin.</p> <p><strong>Şema değişikliği olmayan davranış değişiklikleri.</strong> Alan hâlâ orada, tür aynı, ve değer artık farklı bir şey ifade ediyor. Eskiden <code>active</code> veya <code>inactive</code> olan ve şimdi <code>suspended</code> de döndüren bir <code>status</code>, kapsamlı bir switch'e sahip her çağıranı bozar. Yerel saatten UTC'ye geçen bir timestamp, dokümanları iki kez okumayan herkesi bozar. OpenAPI dosyasının bir diff'inde bunların hiçbiri görünmez.</p> <p><strong>Sıkılaştırılmış doğrulama.</strong> TLD'siz e-postaları, veya sondaki boşlukları, veya 80 karakterden uzun isimleri reddetmeye başlarsınız. Tam olarak bunu gönderen her çağıran şimdi geçen hafta çalışan bir istek için 400 alır. Doğrulama değişiklikleri en yaygın olarak "sıkılaştırma" düzeltmesi olarak gönderilendir.</p> <p><strong>Değişen varsayılanlar.</strong> Değeri açıkça ayarlayan kimse hiçbir şey fark etmez. Ayarlamayan herkes, ki bu çoğu çağırandır, bir satır değiştirmeden yeni davranış alır. Değişen bir varsayılan, kullanıcılarınızın çoğunluğunu tam olarak ayarı hiç görmedikleri için bozar.</p> <h2>Bir breaking change gönderilmeden önce nasıl tespit edilir?</h2> <p>Pull request'teki sözleşmeyi ana daldaki sözleşmeyle CI'da karşılaştırın ve breaking bir farkta build'i başarısız yapın. Çoğu arayüz formatı için şema diff araçları vardır ve her biri kendi formatının breaking kurallarını bilir:</p> <table> <thead> <tr> <th>Arayüz</th> <th>Araç</th> <th>Neyi karşılaştırır</th> </tr> </thead> <tbody><tr> <td>REST (OpenAPI)</td> <td><a href="https://github.com/oasdiff/oasdiff">oasdiff</a></td> <td>İki OpenAPI spec'i, breaking-changes raporuyla</td> </tr> <tr> <td>gRPC (Protobuf)</td> <td><a href="https://buf.build/docs/breaking/">buf breaking</a></td> <td><code>.proto</code> dosyaları, wire veya kaynak düzeyinde</td> </tr> <tr> <td>GraphQL</td> <td><a href="https://github.com/kamilkisiela/graphql-inspector">GraphQL Inspector</a></td> <td>İki şema, breaking ve tehlikeli değişiklikleri işaretler</td> </tr> <tr> <td>Rust crate'leri</td> <td><a href="https://github.com/obi1kenobi/cargo-semver-checks">cargo-semver-checks</a></td> <td>Public API'yi son yayımlanan versiyonla</td> </tr> <tr> <td>TypeScript paketleri</td> <td><a href="https://api-extractor.com/">API Extractor</a></td> <td>Paketin public API'sinin commit edilmiş bir raporu</td> </tr> </tbody></table> <p>Bu araçlar kaldırılmış alanları, yeniden adlandırılmış operasyonları ve değişen türleri güvenilir şekilde yakalar. Yukarıdaki dört türün ilk ikisini, yani kazara bir sözleşmeyi veya bir davranış değişikliğini göremezler, çünkü ikisi de bir şemada görünmez. Aracı bariz olanları durdurmak için, geri kalanı için ise "doğru bir çağıran bunu fark eder miydi?" inceleme sorusunu kullanın. Aynı CI işi, bir changelog girdisini zorunlu kılmak için de doğal bir yerdir; bunu <a href="https://changeloop.dev/blog/tr/changelog-ci-enforcement/">CI'da changelog girdilerini zorunlu kılma</a> anlatır ve <a href="https://changeloop.dev/blog/tr/grpc-protobuf-api-changes/">gRPC ve Protobuf API değişiklikleri</a> wire düzeyindeki durumları ele alır.</p> <h2>Bir breaking change commit'te nasıl işaretlenir?</h2> <p><a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a> ile bir breaking change, iki noktadan önce bir <code>!</code> ile (<code>feat(api)!: remove the legacy export endpoint</code>) veya <code>BREAKING CHANGE:</code> ile başlayan ve bir açıklamanın izlediği bir footer ile işaretlenir. İkisi de bir major versiyona karşılık gelir. Footer'ı changelog girdisinin ilk taslağı olarak yazın: kimin etkilendiğini ve ne yapması gerektiğini söyleyin. <a href="https://changeloop.dev/blog/tr/conventional-commits-changelog/">Conventional commit'ler ve changelog</a>, bu kuralın sizi ne kadar ileri götürdüğünü anlatır.</p> <p>Aynı kural kütüphaneler için de geçerlidir. Kaldırılmış bir public fonksiyon, daraltılmış bir parametre türü veya değişen bir dönüş değeri, semantik versiyonlama altında bir major versiyondur. Kütüphaneler bunu her zaman izlemez: <a href="https://arxiv.org/abs/2110.07889">119.879 Maven Central yükseltmesi üzerine bir çalışma</a>, bunların %16,6'sının semantik versiyonlamayı bozduğunu, ama istemci projelerin yalnızca %7,9'unun etkilendiğini buldu, çünkü bu değişikliklerin çoğu hiçbir istemcinin çağırmadığı koda dokunuyordu. Bozulma, çağıranda ölçülür.</p> <h2>Bir breaking change nasıl gönderilir?</h2> <p>Onu açıkça, bir tarihle, bir yolla gönderirsiniz. Aşağıdaki adımlar sırayla, ve sonuncusu çoğu ekibin atladığıdır: etkilenen insanlara bekledikleri şeyin şimdi olduğunu söylemek.</p> <ol> <li><strong>Öyle olup olmadığına karar verin.</strong> Diff'i değil yukarıdaki testi kullanın. İki mühendis anlaşamıyorsa, breaking'tir; anlaşmazlık bir çağıranın makul bir şekilde eski davranışa dayanabileceğinin kanıtıdır.</li> <li><strong>Versiyonlayın.</strong> <a href="https://semver.org/">Semantik versiyonlama</a> altında bir breaking change bir major versiyondur. Tarihli veya versiyonlu bir API çalıştırıyorsanız, yeni bir versiyona girer ve eski, belirtilen bir tarihe kadar çalışmaya devam eder. Versiyonlayamıyorsanız, bir breaking change göndermiyorsunuz, bir changelog girdisiyle bir kesinti gönderiyorsunuz. Hangi şemanın versiyonu taşıdığı <a href="https://changeloop.dev/blog/tr/api-versioning-best-practices/">API versiyonlama en iyi uygulamaları</a>'nın konusudur.</li> <li><strong>Kod merge edilmeden önce girdiyi yazın.</strong> Girdinin sabit bir şekli vardır: ne değişiyor, kimi etkiliyor, ne yapmaları gerekiyor, ve ne zamana kadar. Dördünü de dolduramıyorsanız, değişiklik hazır değildir. <a href="https://changeloop.dev/release-notes-template">Release notes şablonu</a>, tam olarak bu yüzden bu girdileri bir sürüm numarası yerine bir tarihle önce koyar.</li> <li><strong>Bir sürüm numarası değil bir son tarih verin.</strong> "v5'te kaldırıldı" sürümlerinizi takip etmeyen biri için hiçbir şey ifade etmez. "1 Kasım 2026'da çalışmayı durduruyor" herkes için aynı şeyi ifade eder.</li> <li><strong>Göçü sağlayın.</strong> Eski çağrının yeni olanın yanında bir kod örneği. Değişiklik bir yeniden adlandırmaysa, her iki adı da aynı cümlede söyleyin. Kaldırılmış bir alansa, verinin nereye gittiğini söyleyin.</li> <li><strong>Eski davranışın dokümante edildiği her yerde duyurun.</strong> Changelog, endpoint'i tarif eden doküman sayfası, SDK'nın release notes'u, ve varsa yanıttaki deprecation header'ı. Tek bir yerde duyurulmuş, orayı görmüş olan insanlara duyurulmuştur.</li> <li><strong>Döngüyü kapatın.</strong> Bir müşteri değişikliği istediyse, veya ona yol açan hatayı bildirdiyse, gönderildiğinde ona söyleyin. Bu adım onu kullanıcılarınıza yapılan bir şeyden onlarla yapılan bir şeye dönüştürür.</li> </ol> <h2>İyi bir breaking-change girdisi nasıl görünür?</h2> <p>İyi bir girdi ilk satırda etkilenen çağıranı belirtir, tarihi belirtir, ve düzeltmeyi içerir. İşte sıkılaştırılmış doğrulama durumu için kullandığımız şekilde bir tane:</p> <blockquote> <p><strong>Alan adı olmayan e-posta adresleri 1 Kasım 2026'dan itibaren reddediliyor.</strong> <code>POST /users</code> ve <code>PATCH /users/:id</code> şu anda <code>alice@localhost</code> gibi <code>email</code> değerlerini kabul ediyor. 1 Kasım'dan itibaren bunlar <code>400 invalid_email</code> döndürecek. Dahili dizinlerden kullanıcı oluşturan herhangi bir entegrasyonu etkiler. Göç: tam olarak nitelikli bir adres gönderin, veya alanı atlayıp sonra ayarlayın. Adresleriniz zaten bir alana sahipse hiçbir değişiklik gerekmez, ki bu yıl oluşturulan hesapların %99,4'ü için doğrudur.</p> </blockquote> <p>Bu bildirimin nerede yaşadığı, ve yanında başka nelerin olması gerektiği, <a href="https://changeloop.dev/blog/tr/api-changelog/">API changelog</a>'un konusudur.</p> <p>Sondaki yüzde bir dekorasyon değildir. Okuyucuya endişelenip endişelenmeyeceğini söyler, ki bu girdiyi açtığı sorudur.</p> <h2>Neden onları basitçe önlemiyoruz?</h2> <p>Çünkü alternatif daha kötü. Hiçbir zaman bir şeyi bozmayan bir API, yaptığı her hatayı biriktirir: yanlış adlandırılmış alan, yanlış varsayılan, yerel saatteki timestamp. Her biri, bir öğleden sonrada göç edebilecek çağıranları korumak için her yeni çağıran için sonsuza kadar bir vergidir. En iyi kararlılık itibarına sahip ekipler, nadiren, bir programa göre, bir göç yolu ve hedeflendiği insanlara ulaşan bir uyarıyla bir şeyleri bozar.</p> <p>Bu uyarının mekaniği <a href="https://changeloop.dev/blog/tr/api-deprecation/">bir API'yi deprecate etmek</a> üzerine olan yoldaş makalenin konusudur. Onu duyuran girdi, <a href="https://changeloop.dev/docs">changelog akışındaki</a> başka herhangi bir girdi gibi hazırlanır: merge edilmiş pull request'ten, bir insan için tutulur, sonra etkilenen çağıranların zaten okuduğu yerde yayımlanır.</p> <h2>FAQ</h2> <p><strong>Breaking ile breaking olmayan bir değişiklik arasındaki fark nedir?</strong> Breaking bir değişiklik, doğru bir çağıranı çalışmaya devam etmek için kodunu, yapılandırmasını veya verisini değiştirmeye zorlar. Breaking olmayan bir değişiklik, mevcut her çağrıyı aynı anlamla çalışır bırakır; bu yüzden eklemeler genellikle güvenlidir, kaldırmalar, yeniden adlandırmalar ve sıkılaştırılmış kurallar ise genellikle değildir.</p> <p><strong>Zorunlu bir alan eklemek sayılır mı?</strong> Evet. Mevcut her çağrı onu atlar, bu yüzden mevcut her çağrı şimdi başarısız olur. Onu makul bir varsayılanla isteğe bağlı olarak ekleyin, veya endpoint'i versiyonlayın.</p> <p><strong>Bir hata düzeltmesi sayılır mı?</strong> Olabilir. Çağıranlar hatalı davranışa dayanıyorsa, düzeltmek dokümantasyon ne derse desin onları bozar. Gözlemlenebilir çıktıyı değiştiren herhangi bir düzeltmeyi, kimsenin dayanmadığını gösteremiyorsanız breaking olarak ele alın.</p> <p><strong>Semantik versiyonlama bir web API'sine uygulanır mı?</strong> Kural evet: breaking change'ler yeni bir major versiyon alır ve eski, belirtilen bir süre boyunca çalışmaya devam eder. Numara genellikle bir paket versiyonu yerine URL'de veya bir tarih header'ında yaşar.</p> <p><strong>Ne kadar bildirim yeterli?</strong> Bir çağıranın bildirimi bulup işi yapmasına yetecek kadar. Doksan gün, genel API'ler için yaygın bir taban çizgidir; uzaktan güncellenemeyen ve son kullanıcılara gönderilen kodda kullanılan herhangi bir şey için daha uzun.</p> </article> <article> <h1>Geri bildirim döngüsünü changelog tarafından kapatmak</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Bir müşteri geri bildirim döngüsü, geri bildirimi veren kişiye ona ne olduğu söylendiğinde kapanır. Dosyalandığında değil. Önceliklendirildiğinde değil. Gönderildiğinde bile değil. Ona söylendiğinde. Çoğu ekip ilk üç adımı iyi yapar ve sonuncusunu hiç yapmaz, sonra geri bildirim gönderen insanların neden göndermeyi bıraktığını merak eder.</p> <p>Bu makale o son adım hakkındadır, ve somut bir iddia hakkındadır: changelog, döngüyü kapatmak için doğru yerdir, çünkü döngünün kapatılabileceği anda zaten var olan tek artefakt odur.</p> <h2>Bir müşteri geri bildirim döngüsü nedir?</h2> <p>Bir müşteri geri bildirim döngüsü, bir kullanıcının size bir şey söylemesinden o kullanıcının ne yaptığınızı öğrenmesine giden yoldur. Dört adımı vardır: geri bildirimi toplamak, onunla ne yapılacağına karar vermek, sonucu göndermek, ve isteyen kişiye söylemek. Dördüncü adım gerçekleşene kadar döngü açıktır. Geri bildirim toplayan ve düzeltmeleri gönderen ama hiç kimseye söylemeyen bir ekibin bir gelen kutusu vardır, döngüsü yoktur.</p> <table> <thead> <tr> <th>Adım</th> <th>Ne oluyor</th> <th>Genellikle nerede bozuluyor</th> </tr> </thead> <tbody><tr> <td>Toplamak</td> <td>Geri bildirim gelir: widget, destek, satış, görüşmeler</td> <td>Hiçbir şey; her ekip bunu yapar</td> </tr> <tr> <td>Karar vermek</td> <td>Triyaj edilir, kopyalarla birleştirilir, kabul veya reddedilir</td> <td>Reddedilenler asla iletilmez</td> </tr> <tr> <td>Göndermek</td> <td>Biri onu inşa eder ve canlıya çıkar</td> <td>İsteğe bağlantı merge'de kaybolur</td> </tr> <tr> <td>Söylemek</td> <td>İsteyen kişi gönderildiğini öğrenir</td> <td>Atlanır, veya sadece en sesli isteyen için yapılır</td> </tr> </tbody></table> <p>Dördüncü satır bu makalenin konusudur. Kültürel değil yapısal bir nedenle bozulur: bir özellik gönderilene kadar, ona neden olan istek, gönderilen şeyden farklı bir sistemde yaşar, ve onları bağlamak kimsenin işi değildir. Döngü daha önce, isteğin en başta nasıl istendiğiyle başlar; <a href="https://changeloop.dev/blog/tr/how-to-ask-for-customer-feedback/">müşteriden geri bildirim nasıl istenir</a> ifadeyi ve zamanlamayı ele alır.</p> <h2>Geri bildirim döngüleri neden açık kalır?</h2> <p>Geri bildirim döngüleri açık kalır çünkü istek ve gönderilen değişiklik farklı yerlerde yaşar ve aralarındaki bağlantı, varsa, elle yapılır. İstek bir geri bildirim aracında, bir destek gelen kutusunda veya bir e-tablodadır. Değişiklik bir pull request'tedir. Duyuru bir changelog'da veya bir e-postadadır. Üç sistem, üç sahip, ve üçüncüden birinciye geri bağlantı, aylar sonra kimin sorduğunu hatırlayan bir kişidir.</p> <p>İkinci bir neden var. Söyleme adımı genellikle bir destek görevi ("kişiye cevap vermek") yerine bir pazarlama görevi ("özelliği duyurmak") olarak çerçevelenir. Duyurular herkese gider ve özellikle kimseye ulaşmaz. Mart ayında özelliği isteyen kişi, Haziran duyurusunu, okursa, bir cevap olarak değil bir haber olarak okur. Döngü ancak mesaj ona yönlendirilmişse kapanır.</p> <h2>Döngü neden changelog'dan kapatılmalı?</h2> <p>Çünkü changelog girdisi, tam olarak doğru anda var olan, tam olarak doğru kelimeleri içeren, ve tam olarak doğru kişi tarafından yazılan tek artefakttır. Değişiklik canlı olduğunda var olur, öncesinde değil. Neyin değiştiğini okuyucunun terimleriyle söyler, ki bu isteyen kişinin ihtiyaç duyduğu mesajdır. Ve tam olarak pull request'i okumuş biri tarafından yazılır, ki bu orijinal isteğe olan bağlantının hâlâ görünür olduğu tek andır.</p> <p>Alternatifleri karşılaştırın. Döngüyü geri bildirim aracından kapatmak, geri bildirim aracının özelliğin ne zaman gönderildiğini bilmesi gerektiği anlamına gelir, ki bu birinin elle bir durumu güncellediği anlamına gelir. Onu pull request'ten kapatmak, değişiklik canlı olmadan önce merge'de müşteriye söylemek anlamına gelir, dağıtım geciktiğinde zaman damgalı kırık bir söz. Onu pazarlama duyurusundan kapatmak, biri için beklemek anlamına gelir, ve gönderilen değişikliklerin çoğu asla bir tane almaz.</p> <p>Changelog ortadadır: merge'den sonra, yayın anında, ifade hazır.</p> <h2>Döngü adım adım nasıl kapanır</h2> <p>İşte çalıştırdığımız mekanizma. Burada bir ürün turu yerine bir spesifikasyon olarak tanımlanmıştır, çünkü her adım elle veya başka araçlarla yapılabilir; önemli olan sıradır.</p> <ol> <li><strong>Geri bildirim, onu düzeltecek repository'de bir issue olur.</strong> Bir widget gönderimi, gönderenin e-posta adresi issue gövdesine girmeden etiketli bir GitHub issue'su (<code>feature-request</code> veya <code>bug</code>, bir öncelik, ve <code>from-widget</code>) olarak dosyalanır. Issue kodun yanında yaşar, böylece üçüncü adım onu bulabilir. Elle açılan bir issue, örneğin bir <a href="https://changeloop.dev/blog/tr/feature-request-template/">feature-request-şablonu</a> ile, bu yolun dışındadır: beşinci adım ona yorum yapmaz, bu yüzden o döngüyü kendiniz kapatın.</li> <li><strong>Düzeltme issue'ya referans verir.</strong> Pull request <code>Fixes #142</code> der, GitHub'ın kendi kapatma anahtar kelimesi. Öğrenilecek yeni bir şey yok, ve geliştiricilerin zaten yazdığı aynı cümle.</li> <li><strong>Changelog girdisi, merge edilen pull request'ten hazırlanır ve bağlantıyı taşır.</strong> Merge'de, taslak oluşturulur ve <code>#142</code>, PR gövdesinden okunup taslağa eklenir. Bağlantı, hâlâ ucuzken, bir makine tarafından, zaten orada olan verilerden yapılır.</li> <li><strong>Bir insan girdiyi gözden geçirir.</strong> İfade, hedef kitle, hiç yayımlanıp yayımlanmayacağı. Atılmış bir taslak hiçbir şeyi kapatmaz, ki bu doğrudur: bir issue'ya rastgele referans veren dahili bir refactor haber değildir.</li> <li><strong>Onaylandığında, isteyen kişiye söylenir.</strong> Geri bildiriminin dönüştüğü issue'da bir yorum yayımlanır, "Shipped —" ardından girdinin başlığı ve yayımlanan girdiye bir bağlantı, ve widget gönderene aynı gönderilen girdiyi gösterir. Bir kez, asla iki kez değil, ve sadece bir insan girdiyi yayımladıktan sonra. Aynı girdi <a href="https://changeloop.dev/docs">feed ve widget</a> aracılığıyla sormamış olan herkese gider.</li> </ol> <p>Beşinci adımdaki sıra tüm tasarımdır. İsteyen kişiye merge'de söylemek daha erken ve daha kolay olurdu, ve dağıtımların geciktiği kadar sık yanlış olurdu. Bir feature flag bu sırayı bile bozar, çünkü onaylanmak ve yayınlanmak, özellik isteyen kişinin hesabı için hâlâ görünmezken gerçekleşebilir; <a href="https://changeloop.dev/blog/tr/feature-flags-feature-requests/">feature flag'ler ve özellik talepleri</a> bir flag işin içine girdiğinde bu adımın ihtiyaç duyduğu ek kontrolü ele alır.</p> <h2>Kapalı bir döngü müşteriye nasıl görünür?</h2> <p>Bir cevap gibi görünür. Müşteri bir widget aracılığıyla bir istek gönderdi, ve bir gün widget onu, kendi terimleriyle tanımlayan bir girdiye bağlantıyla birlikte gönderildi olarak gösterir; GitHub'da issue aynı haberi bir yorum olarak alır. Bir bültene abone olmadı, bir roadmap kontrol etmedi, changelog'da aramadı. Ona söylendi.</p> <p>Bu, bir sonraki geri bildirim parçasının gerçekleşmesini sağlayan deneyimdir. İnsanlar cevap veren ürünlere geri bildirim gönderir. <a href="https://changeloop.dev/changelog-examples">Changelog örnekleri</a> sayfası, kullanıcıları görünür şekilde isteklerle geri gelmeye devam eden ekiplerin girdilerini içerir, ve ortak nokta araç değildir; girdilerin cevap gibi okunmasıdır.</p> <h2>Bir geri bildirim döngüsü nasıl ölçülür?</h2> <p>En az bir isteyen kişiyi bilgilendiren gönderilen değişikliklerin oranını, ve gönderme ile bilgilendirme arasındaki zamanı ölçün. Bağlantı var olduğunda kolay, öncesinde imkansız olan iki sayı.</p> <ul> <li><strong>Kapatma oranı</strong>: bu ay yayımlanan changelog girdilerinden kaçı en az bir isteğe bağlantı verdi, ve bunlardan kaçı isteyen kişiyi bilgilendirdi. İkinci sayı birinciden çok daha düşükse, bildirimler başarısız oluyor demektir; birincisi düşükse, istekler pull request'lerden referans alınmıyor demektir, ve düzeltme PR şablonundaki bir cümledir.</li> <li><strong>Gönderme-bilgilendirme süresi</strong>: girdinin canlıya çıkması ile isteyen kişinin bilgilendirilmesi arasında ne kadar geçiyor. Yukarıdaki mekanizma ile saniyeler. Elle tipik olarak haftalar, veya hiç, ve "hiç" önemli olan sayıdır.</li> </ul> <p>Döngüyü toplanan geri bildirim hacmine göre ölçmeyin. Toplamak kolay adımdır, ve onu ölçen bir ekip onu optimize edecektir, ki bu daha fazla açık döngü üretir.</p> <h2>Roadmap nereye uyuyor?</h2> <p>Genel bir roadmap, döngüyü erken kapatmanın bir yoludur: isteyen kişilere, gönderilmeden önce isteklerinin duyulduğunu söyler. Faydalıdır, ve son adımın yerine geçmez. "Planlandı" gelecek hakkında bir sözdür; "Gönderildi" şimdiki zaman hakkında bir gerçektir. <a href="https://changeloop.dev/blog/tr/public-roadmap/">Genel roadmap'i</a> aynı issue'lardan, sütun başına bir etiketle çalıştırın, böylece aynı istek herhangi bir yerde yeniden girilmeden planlanandan gönderilene taşınır. Gönderilene taşıma bir etiket değişikliğidir (<code>roadmap:shipped</code>) ve girdi onaylandığında bunu sizin yerinize hiçbir şey yapmaz, bu yüzden aynı incelemede yapın.</p> <h2>FAQ</h2> <p><strong>Bir müşteri geri bildirim döngüsünün dört adımı nedir?</strong> Toplamak, karar vermek, göndermek, söylemek. Döngü, dördüncü adım gerçekleşene kadar açıktır. Çoğu çerçeve ortaya analiz ve önceliklendirme adımları ekler; bunlar "karar vermek"in inceltmeleridir, ve hiçbiri hiçbir şeyi kapatmaz.</p> <p><strong>Bir istek reddedildiğinde müşterilere söylenmeli mi?</strong> Evet, ve bu döngünün en ihmal edilen mesajıdır. Net bir "bunu yapmayacağız, ve işte nedeni" bekleyişi bitirir. Sessizlik, döngüyü sonsuza kadar açık ve müşteriyi kontrol ediyor bırakır.</p> <p><strong>Döngüyü kapatmak bir özelliği duyurmaktan nasıl farklıdır?</strong> Bir duyuru herkese gider. Döngüyü kapatmak, isteyen insanlara, istedikleri kanaldan bir cevaptır. İkisini de yapın; farklı okuyucular için farklı mesajlardır.</p> <p><strong>Ya isteyen kişi GitHub'da değilse?</strong> Çoğu değildir, ve bu sorun değil. Widget, gönderdikleri şeyin durumunu, gönderilen girdi ve bağlantısı dahil, onlara göstermeye devam eder, bu yüzden yazdıkları sayfanın ötesinde hiçbir şeye ihtiyaçları yoktur. Issue üzerindeki yorum, repository'yi görebilen kişiler içindir.</p> <p><strong>Bu döngü GitHub yerine GitLab veya Bitbucket'ta çalışır mı?</strong> Widget ve changelog çalışır; beşinci adımdaki otomatik yorum bugün için çalışmaz. GitLab veya Bitbucket'taki bir ekip yine de her gönderimi alır, yine de bunu bir issue olarak kaydeder ve yine de talep edene widget'ta bir durum gösterir, ama bu döngüyü tam olarak issue'nun kendisine kapatmak, o entegrasyon var olana kadar elle yaptığınız bir adımdır.</p> </article> <article> <h1>Changelog'a dönüşen feature-request-şablonu</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>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.</p> <p>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.</p> <h2>Bir feature-request-şablonu neyi içermeli?</h2> <p>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.</p> <table> <thead> <tr> <th>Alan</th> <th>Sonra cevapladığı soru</th> <th>Formda olma nedeni</th> </tr> </thead> <tbody><tr> <td>Ne yapmaya çalışıyorsun?</td> <td>İnşa edilen özellik ihtiyaç duyulan mıydı?</td> <td>Amaç herhangi bir somut öneriden daha uzun yaşar</td> </tr> <tr> <td>Bugün seni ne durduruyor?</td> <td>"Bitti" nasıl görünüyor?</td> <td>Düzeltmeyi öngörmeden boşluğu adlandırır</td> </tr> <tr> <td>Bunun yerine ne yapıyorsun?</td> <td>Bu gerçekten ne kadar acil?</td> <td>Acı verici bir geçici çözüm, bir öncelik seçiciden daha güçlü bir sinyaldir</td> </tr> <tr> <td>Sana nasıl bildirelim?</td> <td>"Gönderildi" mesajını kim alır?</td> <td>Çoğu şablonun atladığı alan</td> </tr> </tbody></table> <p>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.</p> <h2>Şablon</h2> <p>Bu, kullandığımız GitHub issue şablonu, form olarak. Bunu <code>.github/ISSUE_TEMPLATE/feature_request.yml</code> 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.</p> <pre><code class="language-yaml">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. </code></pre> <p>İki detay işi yapıyor. <code>labels: ["feature-request"]</code>, 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.</p> <h2>Bir özellik isteği hangi etiketleri taşımalı?</h2> <p>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.</p> <table> <thead> <tr> <th>Etiket</th> <th>Değerler</th> <th>Kim okuyor</th> </tr> </thead> <tbody><tr> <td>Tür</td> <td><code>feature-request</code>, <code>bug</code></td> <td>Hangi kuyruğa gireceğine karar veren</td> </tr> <tr> <td>Öncelik</td> <td><code>priority:low</code>, <code>priority:medium</code>, <code>priority:high</code></td> <td>Sonraki döngüyü planlayan</td> </tr> <tr> <td>Kaynak</td> <td><code>from-widget</code>, <code>from-form</code>, <code>from-support</code></td> <td>İsteklerin nereden geldiğini ölçen</td> </tr> </tbody></table> <p>Widget, bir gönderimi issue olarak dosyalarken ilk iki ekseni ve <code>from-widget</code>'ı uygular; <code>from-form</code> ve <code>from-support</code>, başka yollardan gelen istekler için önerilerdir. Widget'ın etiketleri şunlardır: bir tür (<code>bug</code> veya <code>feature-request</code>, 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 <code>bug</code> ve yüksek), ve <code>from-widget</code>. 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.</p> <p>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.</p> <h2>Bir özellik isteği nasıl bir changelog girdisi olur?</h2> <p>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ı <code>Fixes #142</code> 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.</p> <p>Ş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 <a href="https://changeloop.dev/changelog-tools">changelog araçları</a>, toplama ve bağlantıyı yapabilir; ifade hâlâ bir insana ihtiyaç duyar, ve o insanın amaca ihtiyacı vardır.</p> <h2>Gönderildiğinde ne olur?</h2> <p>İ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.</p> <p>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. <a href="https://changeloop.dev/docs">Feed ve widget</a>, aynı girdiyi sormamış olan herkese taşır, ki bu çoğu insandır; yorum sormuş olanlar içindir.</p> <h2>Çoğu feature-request-şablonu neden başarısız oluyor</h2> <p>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.</p> <h2>FAQ</h2> <p><strong>Bir feature-request-şablonu öncelik sormalı mı?</strong> 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.</p> <p><strong>İsteyenler bir çözüm önermeli mi?</strong> 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.</p> <p><strong>Özellik istekleri genel bir roadmap'te görünmeli mi?</strong> 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. <a href="https://changeloop.dev/blog/tr/public-roadmap/">Genel roadmap</a> makalesi mekanizmadır.</p> <p><strong>Kopyalarla nasıl başa çıkarım?</strong> 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 (<code>Fixes #142, fixes #187</code>).</p> <p><strong>Şablon nerede yaşamalı?</strong> 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.</p> </article> <article> <h1>Issue tracker'ınızdan genel roadmap, üç sütun</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Genel bir roadmap, inşa etmeyi planladığınız şeylerin, müşterilerin görebileceği bir yerde yayımlanmış bir listesidir. İşi yapan kelime <em>planlıyorsunuz</em>: bir roadmap, gelecek hakkında bir dizi sözdür, ve üzerindeki her öğe ya tutacağınız ya da tutmadığınızın görüleceği bir öğedir. Bir tane yayımlamanın nedeni budur, ve aynı zamanda çoğu genel roadmap'in bir çeyrek içinde eskimesinin de nedenidir. Hayatta kalan versiyon küçüktür, zaten sahip olduğunuz veriden türetilmiştir, ve diğer uçta changelog'a bağlıdır, böylece bir söz kimse onu yeniden girmeden bir gerçeğe dönüşür.</p> <h2>Genel bir roadmap ne için var?</h2> <p>Genel bir roadmap, isteği olan bir müşteriye, gönderilmeden önce isteğinin duyulduğunu söyler. Döngüyü kapatmanın erken yarısıdır: "Planlandı" "biri bunu okudu mu" sorusunu cevaplar, ve "İnşa ediliyor" "bu gerçekten oluyor mu" sorusunu cevaplar. Hiçbiri son adımın, gönderildiğinde isteyen kişiye söylemenin yerine geçmez, ama ikisi de bu arada soran insanların sayısını azaltır.</p> <p>Aynı zamanda ekip için bir şey yapar: genel bir taahhüdü zorlar, ki bu kimsenin inşa etmeyeceği dört yüz öğeyi sessizce tutan bir backlog'a karşı bilinen en ucuz çaredir.</p> <table> <thead> <tr> <th>Sütun</th> <th>Yaptığı söz</th> <th>Bir öğeyi içine taşıyan şey</th> </tr> </thead> <tbody><tr> <td>Planlandı</td> <td>Bunu inşa etmeyi planlıyoruz</td> <td>Issue üzerinde etiket olarak kaydedilen bir karar</td> </tr> <tr> <td>İnşa ediliyor</td> <td>Biri şu anda üzerinde çalışıyor</td> <td>Issue üzerinde bir <code>roadmap:building</code> etiketi</td> </tr> <tr> <td>Gönderildi</td> <td>Canlıda</td> <td>Bir <code>roadmap:shipped</code> etiketi, veya bu etiket dururken issue'yu kapatmak</td> </tr> </tbody></table> <p>Sabit sırayla üç sütun yeterlidir. Dördüncü bir sütun ("değerlendiriliyor", "inceleniyor", "backlog") iyi niyetlerin bir müzeye dönüştüğü yerdir, ve müşterilerin görmezden gelmeyi öğrendiği ilk sütundur.</p> <h2>Roadmap'iniz genel olmalı mı?</h2> <p>Küçük ve dürüst tutabiliyorsanız genel yapın; alternatif uzun bir belki listesiyse özel tutun. Genel bir roadmap'in maliyetinin onu yayımlamakla hiçbir ilgisi yoktur: üzerindeki her öğe artık birinin destekte, satış görüşmelerinde ve yenileme konuşmalarında soracağı bir sorudur. İnşa edeceğiniz on öğe bir varlıktır. İnşa edebileceğiniz altmış öğe, neden yapmadığınıza dair altmış gelecek konuşmasıdır.</p> <p>Yayımlamamak için iki dürüst neden: planlarınız bir çeyrekten daha hızlı değişiyor, veya rekabetiniz roadmap'inizi müşterilerinizden daha dikkatli okuyor. İkisi de gerçek, ve ikisi de hiçbir şey yerine daha azını yayımlayarak cevaplanır: sadece "inşa ediliyor", "planlandı" dahili tutularak, yine de isteyen bir kişiye issue'sunun hareket ettiğini söyler.</p> <h2>GitHub issue'larından genel bir roadmap nasıl inşa edilir?</h2> <p>Zaten takip ettiğiniz issue'lara sütun başına bir etiket koyun, ve etiketli issue'ları roadmap olarak görselleştirin. Hiçbir şey yeniden girilmez, roadmap işten uzaklaşamaz, ve bir müşteri isteği olarak başlayan aynı issue kimliğini değiştirmeden sütunlar arasında hareket eder.</p> <p>Mekanizma, çalıştırdığımız şekliyle:</p> <ol> <li><strong>Sabit önek ile sütun başına bir etiket</strong>: <code>roadmap:planned</code>, <code>roadmap:building</code>, <code>roadmap:shipped</code>. Bağlı bir repository'de bunlardan birini taşıyan herhangi bir issue o sütunda görünür. Bunlardan hiçbirine sahip olmayan bir issue roadmap'te değildir, ki bu çoğu issue'dur, ki bu doğrudur.</li> <li><strong>Sütunlar sıralı bir dizidir, her zaman aynı sırada.</strong> Planlandı, inşa ediliyor, gönderildi. İsme göre indekslenmiş bir harita değil, böylece bir okuyucu (veya bir widget) sırayı asla tahmin etmek zorunda kalmaz.</li> <li><strong>Bir issue iki etiket taşıyorsa, en ileride olan kazanır.</strong> Biri <code>roadmap:planned</code>'ı kaldırmadan önce <code>roadmap:shipped</code>'ı ekleyecektir; "hangi webhook son geldi" tarafından yönlendirilen bir durum makinesi, teslimat sırasına bağlı olarak öğeyi farklı sütunlara koyardı. Sadece etiket kümesinden karar vermek, olayların nasıl geldiğinden bağımsız olarak cevabı aynı yapar.</li> <li><strong>Gönderildi, diğerleri gibi bir etiket durumudur.</strong> Kart, issue <code>roadmap:shipped</code> aldığında veya bu etiketi taşırken kapatıldığında taşınır. Kartın kendisi changelog girdisine bağlanmaz; ayrıntılar, issue'yu kapatan pull request'ten hazırlanan girdidedir.</li> <li><strong>Onu veri olarak sunun.</strong> Roadmap, aynı önbellek başlıklarıyla changelog akışının yanında yayımlanan bu üç sütunlu bir JSON belgesidir, böylece bir doküman sitesi, bir widget veya bir durum sayfası ikinci bir entegrasyon olmadan onu görselleştirebilir. <a href="https://changeloop.dev/docs">Feed dokümantasyonu</a> tam şeklini içerir.</li> </ol> <p>Bir etiket, bir maintainer'dan istenecek küçük bir şeydir, ve tüm entegrasyon budur. Senkronize tutulacak bir pano yok, giriş yapılacak ayrı bir araç yok, ve müşterinin dosyaladığı istek roadmap'teki öğedir; gönderildiğinde, aynı öğedir.</p> <h2>Genel bir roadmap neyi içermemeli?</h2> <p>Dokuz ay sonra sorulmasından utanacağınız tarihleri, tahminleri, veya herhangi bir şeyi içermemelidir. Tarihler klasik hatadır: bir roadmap'teki bir çeyrek bir satış sunumunda bir taahhüde dönüşür, "Q3 dediniz" adında bir bilete dönüşür. Sütunlar yeterince söyler. "İnşa ediliyor" zaten "biri üzerinde olacak kadar yakında" anlamına gelir.</p> <p>Ayrıca dahili backlog'u içermemelidir. Üç yüz öğesi olan bir roadmap bir söz değil bir arama sorunudur, ve isteğini 212. pozisyonda bulan müşteri ona söylemek istemediğiniz bir şey öğrenmiştir.</p> <h2>Roadmap changelog'a nasıl bağlanır?</h2> <p>Roadmap ve changelog aynı issue'ları iki taraftan anlatır, biri gelecek için biri geçmiş için. Kimse ayrı bir panoda kart taşımaz. Bir maintainer zaten üzerinde çalıştığı issue'nun etiketini değiştirir, girdi pull request'ten hazırlanır, ve bir insan o girdiyi onayladığında widget geri bildirimi o issue'ya dönüşen isteyen kişi orada bilgilendirilir. Kartı gönderildi'ye taşımak yine ayrı bir adımdır, <code>roadmap:shipped</code> etiketi, bu yüzden onu aynı incelemenin parçası yapın; girdiyi onaylamak bunu sizin yerinize yapmaz.</p> <p>Bu, <a href="https://changeloop.dev/blog/tr/customer-feedback-loop/">geri bildirim döngüsü makalesinin</a> changelog tarafından tarif ettiği aynı döngüdür; roadmap müşterinin ortasında gördüğü şeydir. <a href="https://changeloop.dev/changelog-tools">Changelog araçları</a> özeti, hangi ürünlerin bir roadmap görünümü sunduğunu ve hangilerinin onu ayrı bir pano olarak ele aldığını kapsar, ki bu doğru kalıp kalmadığına karar veren farktır.</p> <h2>İyi bir genel roadmap nasıl görünür?</h2> <p>Kısa görünür, ve üzerindeki her öğe herkesin açabileceği bir issue'dur. Test, bir müşterinin bir öğeden arkasındaki tartışmaya, ve gönderilen bir öğeden gerçekte neyin değiştiğini tarif eden girdiye gidip gidemeyeceğidir. Girişi olmayan özellik isimlerinin bir listesi olan bir roadmap bir broşürdür.</p> <p>Bir widget'ın getireceği JSON olarak işlenmiş bir örnek:</p> <pre><code class="language-json">{ "columns": [ { "column": "planned", "hasMore": false, "items": [ { "id": "6b0c1f...", "column": "planned", "publicTitle": "Saved views on the inbox", "publicDescription": "Keep a filter you use often and come back to it.", "publishedAt": "2026-09-16T10:04:11.000Z" } ]}, { "column": "building", "hasMore": false, "items": [ { "id": "71a4e2...", "column": "building", "publicTitle": "Roadmap column in the widget", "publicDescription": "See what is coming without leaving the page.", "publishedAt": "2026-09-12T08:20:02.000Z" } ]}, { "column": "shipped", "hasMore": false, "items": [ { "id": "5c9d70...", "column": "shipped", "publicTitle": "Feedback filed as labelled issues", "publicDescription": "Widget submissions arrive as issues your triage already handles.", "publishedAt": "2026-09-02T15:41:37.000Z" } ]} ], "enabled": true, "language": "en" } </code></pre> <p>Üç sütunda üç öğe, mükemmel iyi bir genel roadmap'tir. Neyin geldiğini, neyin olduğunu, ve neyin olmuş olduğunu söyler, ve her satırı kontrol edilebilir. Now/Next/Later'dan sonuç bazlıya kadar beş başka düzen, örnek maddelerle <a href="https://changeloop.dev/blog/tr/product-roadmap-examples/">ürün roadmap örnekleri</a> yazısında gösteriliyor.</p> <h2>FAQ</h2> <p><strong>Genel bir roadmap'te kaç öğe olmalı?</strong> Savunabileceğiniz kadar az. Tüm sütunlarda on'un altı küçük bir ürün için normaldir; "planlandı"da otuzdan fazlası genellikle bir roadmap kılığındaki bir backlog'dur.</p> <p><strong>Genel bir roadmap'te tarihler olmalı mı?</strong> Hayır. Sütunlar, bir son tarih yaratmadan sıra iletir. Bir müşterinin bir tarihe ihtiyacı varsa, bu bir konuşmadır, bir roadmap öğesi değil.</p> <p><strong>Müşteriler roadmap öğeleri için oy vermeli mi?</strong> Oylar kimin geldiğini ölçer, neyin önemli olduğunu değil. Bugün kullandıkları geçici çözümü açıklayan issue üzerindeki bir yorum, elli oydan daha değerlidir, ve oy verene bir şeye mal olur, ki bu önemli olan noktadır.</p> <p><strong>İptal edilen bir roadmap öğesine ne olur?</strong> Etiketi kaldırın ve issue üzerinde nedenini söyleyin. Genel bir "bunu yapmayacağız" döngünün bir parçasıdır, ve çoğu ekibin hiç göndermediği mesajdır.</p> </article> <article> <h1>Changelog otomasyonu, ve sınırları</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Changelog otomasyonu, toplama, sınıflandırma ve yayımlamayı otomatikleştirdiğinde işe yarar, ve seçim ile ifadede durur. Her şeyi otomatikleştirin ve biçimlendirilmiş bir git log gönderirsiniz; hiçbirini otomatikleştirmeyin ve changelog sürümlerden önce, hafızadan, ani atılımlarla yazılır. Faydalı soru hangi kısımları otomatikleştireceğinizdir, ne kadarını değil.</p> <p>Changelog otomasyon projeleri iki yönden birinde başarısız olur, ve her ikisi de ilk tasarım toplantısından tahmin edilebilir. Çok az otomatikleştirin ve changelog birinin güncellemesi gereken bir belge haline gelir, ki bu kısa çöp çekeni kim aldıysa onun tarafından ani atılımlarla güncellendiği anlamına gelir. Çok fazla otomatikleştirin ve biçimlendirilmiş bir git log haline gelir: eksiksiz, doğru, ve kimsenin okumadığı.</p> <h2>Bir changelog'un hangi kısımları otomatikleştirilmeli?</h2> <p>Dört adımdan üçü. Toplama ve yayımlama tamamen; sınıflandırma insan müdahalesiyle ilk geçiş olarak; seçim ve ifade asla.</p> <table> <thead> <tr> <th>Adım</th> <th>Otomatikleştir mi?</th> <th>Neden</th> </tr> </thead> <tbody><tr> <td>Toplama: commit'lerden, PR'lardan, ticket'lardan bir listeye değişiklikler</td> <td>Tamamen</td> <td>Sıkıcı, son tarih altında atlanır, makineler mükemmel yapar</td> </tr> <tr> <td>Sınıflandırma: Added, Fixed, Changed, Deprecated, Removed, Security</td> <td>İlk geçiş, insan müdahalesi</td> <td>Sadece metadata'dan yaklaşık %80 doğru; yanlış %20 önemli olan girdilerdir</td> </tr> <tr> <td>Seçim ve ifade: okuyucuya ne söylenmeli, ve nasıl</td> <td>Asla</td> <td>Artefaktın tüm değeri budur</td> </tr> <tr> <td>Yayımlama: sayfa, akış, e-posta, widget, Slack</td> <td>Tamamen, tek kaynaktan</td> <td>Çoğu manuel çabanın gerçekte gittiği yer</td> </tr> </tbody></table> <p><strong>Toplama.</strong> Değişiklikleri gerçekleştikleri yerden (commit'ler, PR'lar, ticket'lar) alıp bir listeye koymak. Bunu tamamen otomatikleştirin. İnsanlar bunda kötüdür, sıkıcıdır, ve son tarih altında atlanan adımdır. <a href="https://changeloop.dev/blog/tr/conventional-commits-changelog/">Conventional commits</a> veya PR etiketleri genellikle ham malzemedir.</p> <p><strong>Sınıflandırma.</strong> Bir şeyin Added, Fixed, Changed, Deprecated, Removed veya Security olup olmadığına karar vermek. Commit türünden veya PR etiketinden ilk geçişi otomatikleştirin, ve bir insanın geçersiz kılmasına izin verin. Buradaki doğruluk sadece metadata'dan yaklaşık yüzde seksendir, ve yanlış yüzde yirmi tam olarak önemli olan girdilerde yoğunlaşır, çünkü belirsizlik önemle korelasyon gösterir.</p> <p><strong>Seçim ve ifade.</strong> Bir okuyucuya ne söylenmesi gerektiğine ve nasıl söyleneceğine karar vermek. <strong>Bunu otomatikleştirmeyin.</strong> Artefaktın tüm değeri budur. Geri kalan her şey lojistiktir.</p> <p><strong>Yayımlama.</strong> Tamamlanmış girdileri bir sayfaya, bir akışa, bir e-postaya, uygulama içi bir widget'a, bir Slack kanalına götürmek. Tamamen, ve tek bir kaynaktan otomatikleştirin. Çoğu manuel çabanın gerçekte gittiği yer burasıdır, ve neredeyse kimse bunu saymaz. Aynı zamanda değişikliği isteyen kişiye gönderildiğini söyleyebilen adımdır, ki bu <a href="https://changeloop.dev/blog/tr/customer-feedback-loop/">geri bildirim döngüsünü changelog tarafından kapatmak</a>'ın tamamıdır. E-posta yarısının, <a href="https://changeloop.dev/blog/tr/product-update-email/">ürün güncellemesi e-posta şablonu</a>'nda kendi biçimi var.</p> <p>Son nokta üzerinde durmaya değer. Ekipler changelog'u bir yazma sorunu olarak görme eğilimindedir, ve sonra çoğu zamanı dağıtıma harcarlar: girdileri bir e-posta aracına kopyalamak, uygulama içi için yeniden biçimlendirmek, Slack'e yapıştırmak, bir doküman sayfasını güncellemek. Yazmak bir saat sürer. Kopyalamak her sürüm için bir saat sürer, sonsuza dek, ve bu bir makinenin sahip olması gereken kısımdır.</p> <h2>Çizgi kaydığında ne olur?</h2> <p><strong>Yukarı kaydırın ve bir git dump'ı alırsınız.</strong> Commit'lerden tam otomasyon, müşterilerin önünde <code>bump deps</code>, <code>fix flaky test</code>, <code>wip</code> ve <code>address review comments</code> üretir. Bunu yapan her ekip sonrasında bir filtre eklemiştir, ve filtre başka bir isim altında yeniden tanıtılmış, daha kötü ergonomiye sahip bir seçim adımıdır.</p> <p><strong>Aşağı kaydırın ve ani atılımlar alırsınız.</strong> Tamamen manuel toplama, girdilerin sürüm zamanında hafızadan yazıldığı anlamına gelir. Bu, <a href="https://changeloop.dev/blog/tr/keep-a-changelog-implemented/">Keep a Changelog</a>'un en başta uyardığı moddur, ve sessizce bozulur: changelog, kimsenin vakti olmadığı haftaya kadar bakımlı görünür.</p> <h2>Bir changelog otomasyon pipeline'ı nasıl görünür?</h2> <p>Bir taslağın halka açık hale geldiği yere yerleştirilmiş tam olarak bir insan kapısı ile dört adım.</p> <ol> <li>Merge'de, PR'dan bir taslak girdi türetin: etiketten veya commit önekinden tür, ilk taslak olarak başlık, PR'a geri bağlantı, kaydedilen yazar. Yayımlanmamış bir kovaya yerleştirin.</li> <li>Herkes herhangi bir zamanda herhangi bir taslağı düzenleyebilir, ve düzenlemek ucuzdur. Çoğu bir satırlık yeniden yazım alır.</li> <li>Bir sürüm kesmek, kovadaki her girdinin ya düzenlenmiş ya da açıkça dahili olarak işaretlenmiş olmasını gerektirir. Bu kapı tüm tasarımdır. Onsuz, taslaklar meşgul haftada düzenlenmemiş olarak gönderilir.</li> <li>Yayımlamak, yayımlanmış setten bir fan-out'tur: genel sayfa, akış, e-posta, widget, Slack gönderisi. Tek kaynak, birden çok görselleştirme, kopyalama yok.</li> </ol> <p>Adım 3, bir insanın gerekli olduğu tek yerdir, ve taslaklar makul olduğunda sürüm başına yaklaşık on dakika sürer. Bir müşteri talebinin dahil olduğu yerde, taslak ayrıca kapattığı issue'yu taşır, ki bu adım 4'ün talep edeni bilgilendirmesini sağlayan şeydir; <a href="https://changeloop.dev/blog/tr/feature-request-template/">feature-request-şablonu</a> bu bağlantının hayatta kalması için tasarlanmıştır. Bu adımın daha geniş release akışında nerede durduğu <a href="https://changeloop.dev/blog/tr/release-management-process/">release yönetimi süreci</a> yazısının konusudur.</p> <h2>Otomasyon verilerinizden ne gerektirir?</h2> <p>Yukarıdakilerin hiçbiri, changelog bir Markdown dosyasıysa çalışmaz, çünkü bir dosya yeniden parse edilmeden beş yüzeye görselleştirilemez, ve düz yazıyı parse etmek yarım bir başlık gösteren bir widget'la sonuçlanmanızın yoludur.</p> <p>Girdilerin yapılandırılmış olması gerekir: bir tür, bir tarih, bir sürüm veya sürüm tanımlayıcısı, bir hedef kitle, bir gövde ve bir bağlantı. O zaman dosya, sayfa, akış ve e-posta hepsi görünümlerdir. Bu yapısal nokta, bir araç seçmeden önce doğru yapmaya değer olan tek şeydir, çünkü bu ucuza sonradan ekleyemeyeceğiniz şeydir. Bunların hiçbiri, ihtiyaç duyan her değişiklik için gerçekten bir kayıt oluşturulmadıkça çalışmaz; <a href="https://changeloop.dev/blog/tr/changelog-ci-enforcement/">CI'da bir changelog kaydını zorunlu kılmak</a> bu adımı hafızaya bırakmak yerine pipeline'ın kayıtsız merge'ü nasıl reddedeceğini ele alır.</p> <p>Changelog'un önce bir akış sonra bir sayfa olduğu <a href="https://changeloop.dev/">changeloop</a>'u inşa ediyoruz, bu yüzden bunu tarafsız bir öneri yerine bir çıkar olarak okuyun; <a href="https://changeloop.dev/pricing">fiyatlandırma</a> kartsız bir ücretsiz repository'dir, şekli görmeye yeterlidir. <a href="https://changeloop.dev/changelog-tools">Changelog araçları</a> rakip olduğumuz ürünler dahil, başka ne olduğunun özetimizdir, ve <a href="https://changeloop.dev/changelog-generator">changelog üreticisi</a> bir pipeline'a bağlanmadan önce türetmeyi görmek isterseniz toplama ve sınıflandırma adımlarını tarayıcıda yapar.</p> <h2>Test</h2> <p>Bir değişikliğin merge edilmesi ile o değişikliğin repo'nuzu okumayan bir müşteri için görünür olması arasındaki dakikaları sayın. Bu dakikaların çoğu birinin araçlar arasında metin kopyalamasıysa, ihtiyacınız olan otomasyon yazmada değil yayımlamadadır.</p> <h2>FAQ</h2> <p><strong>Yapay zeka changelog'u yazabilir mi?</strong> Bir taslak hazırlayabilir. Merge edilmiş pull request'i verilen bir model çoğunlukla başlık ve gövdenin kullanılabilir bir ilk taslağını üretir, ki bu toplama ve sınıflandırma adımlarının daha iyi yapılmasıdır. Seçim, bir okuyucuya bir şey söylenip söylenmemesi gerektiği, ve son ifade hâlâ hedef kitleyi bilen kişiye ihtiyaç duyar, ve o kapı olmadan taslak yayımlayan bir pipeline yanlış adımı otomatikleştirmiştir.</p> <p><strong>Bir changelog üreticisi ile changelog otomasyonu arasındaki fark nedir?</strong> Bir üretici commit'leri talep üzerine bir kez biçimlendirilmiş bir listeye dönüştürür. Otomasyon her merge'de çalışır, yayımlanmamış bir kova tutar, sürümü insan incelemesine bağlar, ve tek bir kaynaktan her yüzeye yayımlar. Üretici, elle çalıştırılan pipeline'ın ilk adımıdır.</p> <p><strong>Changelog commit'lerden mi yoksa pull request'lerden mi otomatikleştirilmeli?</strong> Değişim biriminin PR olduğu pull request'lerden: başlık ve açıklama tüm değişiklik için bir kez yazılır, ve PR kapattığı issue'yu bağlar. Commit tabanlı türetim, commit birim olduğunda ve bir konvansiyonu takip ettiğinde işe yarar.</p> <p><strong>Otomasyonun dahili değişiklikleri yayımlaması nasıl önlenir?</strong> <code>chore</code>, <code>ci</code>, <code>test</code>, <code>refactor</code> ve bağımlılık güncellemelerini varsayılan olarak dahili sınıflandırın, ve genele terfiyi bilinçli bir eylem yapın. Kimse gizlemedikçe genel olan ters varsayılan, <code>bump deps</code>in müşterilere nasıl ulaştığıdır.</p> </article> <article> <h1>Changelog vs release notes: fark nedir?</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Bir changelog, bir şey arayan biri için yazılmış, değişen her şeyin sürekli, birikimli bir kaydıdır. Release notes ise, onu ilgilendirip ilgilendirmediğine karar veren biri için yazılmış, tek bir sürüm hakkında özenle seçilmiş bir mesajdır. Fark biçimlendirmede değil hedef kitlededir, ve çoğu ekibin ikisine de ihtiyacı vardır: biri referans olarak, biri duyuru olarak, aynı girdilerden türetilmiş.</p> <p>Çoğu ekip birine kazara diğerine talep üzerine sahip olur. Bir geliştirici neyin yayımlandığının bir kaydını istediği için bir changelog'la başlarsınız. Aylar sonra destekten biri müşterilerin Nisan'dan beri canlı olan bir özelliği neden bilmediğini sorar, ve artık release notes'a ihtiyacınız var.</p> <h2>Changelog vs release notes, yan yana</h2> <table> <thead> <tr> <th></th> <th>Changelog</th> <th>Release notes</th> </tr> </thead> <tbody><tr> <td>Okuyucu</td> <td>Bir şey arayan biri</td> <td>İlgilenip ilgilenmeyeceğine karar veren biri</td> </tr> <tr> <td>Kapsam</td> <td>Değişen her şey</td> <td>Bu sürüm hakkında söylenmeye değer olan</td> </tr> <tr> <td>Sıklık</td> <td>Sürekli, merge veya sürüm başına</td> <td>Sürüm başına, ve sadece duyurulmaya değer olanlar</td> </tr> <tr> <td>Ton</td> <td>Kısa, gerçekçi, sık sık emir kipi</td> <td>Açıklayıcı, bazen ikna edici</td> </tr> <tr> <td>Ömür</td> <td>Kalıcı, yıllar sonra da okunur</td> <td>İlk hafta okunur, sonra arşivlenir</td> </tr> <tr> <td>Yaşadığı yer</td> <td>Repo, bir doküman sitesi, bir <code>/changelog</code> sayfası</td> <td>E-posta, uygulama içi, bir blog yazısı, bir sürüm sayfası</td> </tr> <tr> <td>Başarısız olduğu şey</td> <td>Eksik olmak</td> <td>Sıkıcı olmak, veya olaydan sonra gelmek</td> </tr> </tbody></table> <h2>Bir changelog nedir?</h2> <p>Bir changelog, en yeniden başlayarak, her girdi türlendirilmiş (added, changed, deprecated, removed, fixed, security) ve tarihli, kronolojik, neredeyse eksiksiz bir değişim kaydıdır. Okuyucusu zaten ilgilendiğine karar vermiştir. Bir şey arıyor: bir davranış ne zaman değişti, bir hata düzeltildi mi, hangi sürüm bir flag getirdi. Eksiksizlik tüm değerdir, bu yüzden <a href="https://changeloop.dev/blog/tr/keep-a-changelog-implemented/">Keep a Changelog</a> konvansiyonu tek sayfasının çoğunu yapıya harcar ve neredeyse hiçbirini düz yazıya.</p> <h2>Release notes nedir?</h2> <p>Release notes, düz yazı olarak yazılmış, seçici bir mesajdır, tek bir sürüm hakkında. Okuyucusu henüz hiçbir şeye karar vermemiştir. Bu sürümün onu ilgilendirip ilgilendirmediğine, ve bir şey yapması gerekip gerekmediğine karar veriyor. Seçim tüm değerdir: her şeyi listeleyen bir release note, paragraflı bir changelog'dur, ve bir şeyleri atlayan bir changelog okuyucusunu nasıl başarısız kılıyorsa aynı şekilde okuyucusunu başarısız kılar. <a href="https://changeloop.dev/blog/tr/how-to-write-release-notes/">Release notes nasıl yazılır</a> seçim ve ifadelendirme hakkındadır.</p> <h2>Hem bir changelog'a hem release notes'a ihtiyacınız var mı?</h2> <p>İki hedef kitleniz farklı şeyler istediğinde ikisine de ihtiyacınız var; o zamana kadar iki işi yapan tek bir artefakt doğrudur. Küçük ekipler, her girdinin başında kısa bir paragraf içeren tek bir <code>/changelog</code> sayfası yayımlar, ve bir süre bu bir düzeltme arayan geliştiriciye ve haberleri tarayan bir müşteriye eşit derecede hizmet eder. Çok erken bölmek size sürdürülecek iki şey verir ve ikisinden biri çürür.</p> <p>Bölünme şu olmaya başladığında değerli hale gelir:</p> <ul> <li>Changelog girdileriniz geliştiricilerin kaydırıp geçtiği açıklayıcı paragraflara büyümüştür.</li> <li>Ya da tam tersi: sürüm duyurularınız bağımlılık güncellemelerini listelemeye başlamıştır.</li> <li>Destek girdileri e-postalara kopyalıyor ve yolda yeniden yazıyor.</li> <li>Biri "sadece breaking change'ler" istiyor ve onları filtreleyemiyorsunuz.</li> </ul> <p>Sonuncusu gerçek işarettir. Kimse her şeyi okumadan "beni etkileyen ne değişti" diye cevap veremiyorsa, iki işi kötü yapan tek bir artefaktınız var demektir.</p> <h2>Tek bir kaynak, iki görünüm</h2> <p>Hata onları iki belge olarak ele almaktır. Aynı değişiklik kümesinin iki görünümüdür.</p> <p>Changelog'u ilerledikçe yazın, anlamlı her değişiklik için bir girdi, her biri ne olduğuyla etiketlenmiş: fixed, added, changed, removed, deprecated, security. Girdileri birini yazmanın bir karar olmayacağı kadar kısa tutun. Sonra, sürüm zamanında, release notes bir seçim ve yeniden yazımdır: bir insanı ilgilendiren girdileri alın, birine ne yapmasını sağladıklarına göre gruplandırın, ve nedeni en üste koyun.</p> <p>Bunun pratik bir sonucu var. Changelog kaynaksa, yapılandırılmış veri olması gerekir, elle tutulan bir sayfa değil. Bir girdinin bir türe, bir tarihe, bir sürüme, ve kim için olduğunu söyleyen bir yola ihtiyacı vardır. Bunu sahip olduğunda, genel sayfa, uygulama içi widget ve RSS veya JSON feed'i tek bir şeyin üç görselleştirmesi olur, ve kimse bir müşteriye giden yolda hiçbir şeyi yeniden yazmaz. Bir release notes e-postası, e-postanızı hangi araç gönderiyorsa oradan aynı girişi alıntılayabilir. <a href="https://changeloop.dev/blog/tr/changelog-automation/">Changelog otomasyonu</a> bu adımlardan hangisinin bir makineye ait olması gerektiğiyle ilgilidir. Bu, bir changelog'u sayfa yerine bir akış olarak ele almanın tüm argümanıdır. Aynı zamanda, tam şeffaflıkla, bizim inşa ettiğimiz şeydir, bu yüzden bunu tarafsız bir araştırma yerine bir çıkar olarak okuyun.</p> <h2>Sadece birine vaktiniz varsa</h2> <p>Changelog'u yazın. Girdi başına daha ucuzdur, yazdığınız gün faydalıdır, ve release notes daha sonra ondan türetilebilir. Tersi doğru değildir: on iki duyuru e-postasından bir yıllık değişikliği yeniden oluşturamazsınız, ve insanlar sizden bunu isteyecektir.</p> <p>Türetmenin mümkün kalması için sabit bir formatta tutun. <a href="https://changeloop.dev/changelog-examples">Changelog örnekleri</a> sayfamız bunu iyi yapan ekiplerin girdilerini toplar, ve <a href="https://changeloop.dev/release-notes-template">release notes şablonu</a> bir girdi setini göndermeye değer bir şeye dönüştürürken kullandığımız formdur.</p> <h2>Adlandırma üzerine bir not</h2> <p>Bunların hiçbiri standardize değildir, ve "release notes"un sürekli bir liste için, "changelog"un üç aylık bir duyuru için kullanıldığını göreceksiniz. Kelimeler hakkında tartışmak buna değmez. İki işten hangisini her artefaktınızın yaptığına karar verin, onu ekibinizin zaten çağırdığı gibi adlandırın, ve ikisinin de sessizce ikisini birden yapmadığından emin olun.</p> <p>Sonucun hangi yüzeyde bittiği ayrı bir karardır, <a href="https://changeloop.dev/blog/tr/changelog-page/">bir changelog sayfası nasıl kurulur</a>'da ele alınır.</p> <h2>FAQ</h2> <p><strong>Bir changelog release notes ile aynı şey midir?</strong> Hayır. Bir changelog, bir şey arayanların okuduğu eksiksiz kayıttır; release notes, ilgilenip ilgilenmeyeceğine karar verenlerin okuduğu seçilmiş duyurudur. Aynı değişiklik ikisinde de görünür, her okuyucu için farklı ifade edilmiş olarak.</p> <p><strong>Release notes bir changelog'dan oluşturulabilir mi?</strong> Evet, ve bu doğru yöndür. Bir insanı ilgilendirecek girdileri seçin, sonuca göre gruplayın, başlığı yeniden yazın. Tersi, bir changelog'u duyurulardan yeniden oluşturmak, duyuruların dışarıda bıraktığı her şeyi kaybeder.</p> <p><strong>Bir changelog nerede yaşamalı?</strong> Okuyucunun bir depoya ihtiyaç duymadan ulaşabileceği kalıcı ve bağlanabilir bir yerde: bir <code>/changelog</code> sayfası, bir doküman sitesi, veya birden çok yerde görselleştirilen bir akış. Tek başına bir <code>CHANGELOG.md</code> katkıda bulunanlara ulaşır, müşterilere değil.</p> <p><strong>Bir changelog dahili değişiklikleri içermeli mi?</strong> Evet, en altta, her biri bir satır. Changelog eksiksiz kayıttır. Release notes da onları kısa bir son bölümde tutabilir, yeter ki okuyucunun fark edeceği değişiklikler önce gelsin.</p> </article> <article> <h1>Conventional commits'ten bir changelog'a</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Conventional commits bir changelog'a ücretsiz üç şey verir: her değişikliğin türü, dokunduğu sistem parçası, ve bir şeyi bozup bozmadığı. Başka bir şey vermezler. Changelog olan ifade, gruplandırma ve seçim tamamen açık kalır, ve aksini iddia eden bir pipeline biçimlendirilmiş bir git log gönderir.</p> <pre><code>feat(exports): add CSV column selection fix(auth): reject expired refresh tokens chore(deps): bump node-pg to 8.11 </code></pre> <p><a href="https://www.conventionalcommits.org/">Conventional Commits</a> formatında üç commit. Bunlardan, bir makine size birinin özellik, birinin düzeltme, birinin ev işi olduğunu, ve her birinin sistemin hangi parçasına dokunduğunu söyleyebilir. Bu gerçekten faydalıdır, ve konvansiyonun tüm sözü budur: bir insandan başka bir şey tarafından okunabilen bir commit geçmişi. Hata, bunun size bir changelog verdiğini düşünmektir. Size ham malzemeyi verir.</p> <h2>Konvansiyon neyi belirtir?</h2> <p>Bir tür, isteğe bağlı bir scope, ve bir açıklama: <code>type(scope): description</code>. Türler geleneksel olarak <code>feat</code>, <code>fix</code>, <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>perf</code>, <code>build</code>, <code>ci</code>'dir. İki şey bir breaking change'i işaretler: iki nokta üst üsteden önce bir <code>!</code>, veya bir <code>BREAKING CHANGE:</code> footer'ı. Araçlar minor ve patch sürüm artışları için <code>feat</code> ve <code>fix</code>'e, major için breaking belirtecine göre hareket eder.</p> <table> <thead> <tr> <th>Commit size verir</th> <th>Changelog'un ihtiyacı olan</th> <th>Boşluğu kim doldurur</th> </tr> </thead> <tbody><tr> <td><code>feat</code> / <code>fix</code> / <code>chore</code></td> <td>Added / Fixed / dahili</td> <td>Bir eşleme, otomatik</td> </tr> <tr> <td><code>(scope)</code></td> <td>Okuyucunun tanıdığı bir gruplandırma</td> <td>Bir kişi, scope başına bir kez</td> </tr> <tr> <td><code>!</code> veya <code>BREAKING CHANGE:</code></td> <td>Kimin ne zamana kadar bozulacağı ve ne yapılacağı</td> <td>Bir kişi, her seferinde</td> </tr> <tr> <td>Bir gözden geçiren için yazılmış açıklama</td> <td>Bir müşteri için yazılmış sonuç</td> <td>Bir kişi, her girdi</td> </tr> <tr> <td>Bir commit</td> <td>Birden çok commit olabilecek bir değişiklik</td> <td>Squash kuralları, veya bir kişi</td> </tr> </tbody></table> <p>Belirteç bunu araca söyler; çağırana söylemez, ki bu <a href="https://changeloop.dev/blog/tr/api-deprecation/">bir API nasıl deprecate edilir</a> ve <a href="https://changeloop.dev/blog/tr/breaking-changes/">breaking change nedir</a>'in konusudur. Bu küçük bir spesifikasyondur ve ondan hiçbir şey üretmeseniz bile takip etmeye değer, çünkü commit başına bir karar zorlar: bu kullanıcıların gördüğü bir değişiklik mi, değil mi.</p> <h2>Conventional commits nerede durur?</h2> <p>Cümlede dururlar. Konvansiyonun yakaladığı her şey bir değişiklik hakkında metadata'dır; değişimin kendisi hâlâ bir gözden geçirenin kelime dağarcığında tarif edilir.</p> <p><strong>Commit mesajları gözden geçirenler için yazılır.</strong> <code>fix(auth): reject expired refresh tokens</code> doğrudur ve bir müşteriye hiçbir şey söylemez. Bir changelog'un okuyucusu "bir oturum gerçekten süresi dolduğunda çıkış yapacaksınız, ara sıra 401 görmek yerine" ister.</p> <p><strong>Scope'lar dahilidir.</strong> <code>exports</code>, <code>auth</code>, <code>ingest</code> modül isimleridir. Kararlıdırlar, ki bu onları gruplamak için iyi yapar, ve kod tabanının dışındaki herkes için anlamsızdırlar.</p> <p><strong>Bir değişiklik genellikle birden çok commit'tir.</strong> On bir commit'te merge edilen bir özellik on bir girdi üretir, onu gürültü olan, ve bunu gizlemek için squash yapmak inceleme geçmişini kaybettirir.</p> <p><strong><code>chore</code> bir kategori değil bir çöp kutusudur.</strong> Bağımlılık güncellemeleri, CI değişiklikleri ve yeniden adlandırmaların hepsi oraya iner, ve bazıları kullanıcılar için önemliyken çoğu değildir.</p> <p>Yani: konvansiyon size tür, scope ve breaking durumunu ücretsiz verir, ve ifadeyi, gruplandırmayı ve seçimi tamamen açık bırakır. Bu üçü changelog'dur. <a href="https://changeloop.dev/blog/tr/changelog-entry-ownership/">Bir changelog kaydının sahibi gerçekte kimdir</a> o ifadeyi, gruplandırmayı ve seçimi kimin üstlenmesi gerektiğini ele alır, çünkü konvansiyonun kendisinin bu konuda hiçbir görüşü yoktur.</p> <h2>Conventional commits'ten bir changelog nasıl üretilir?</h2> <p>İki katmanda, ve ikincisi zorunlu olmalı.</p> <p><strong>Katman bir, otomatik.</strong> Merge'de, commit'ten bir taslak girdi türetin: bir changelog türüne eşlenmiş tür (<code>feat</code> Added'a, <code>fix</code> Fixed'e, bir flag ile Changed'e bir breaking belirteci), metin yerine metadata olarak tutulan scope, PR'a bağlantı. <a href="https://changeloop.dev/blog/tr/keep-a-changelog-implemented/">Keep a Changelog</a>'un istediği Unreleased bölümüne yerleştirin.</p> <p><strong>Katman iki, insan, ve gerekli.</strong> Bir sürüm çıkmadan önce, her taslak girdi ya kullanıcının kelime dağarcığında bir satırlık yeniden yazım alır, ya da dahili olarak işaretlenir ve genel görünümden çıkarılır. Bu, insanların atlamaya çalıştığı adımdır, ve atlamak diff gibi okunan changelog'lar üretir.</p> <p>Önemli tasarım detayı, katman ikinin pipeline'da isteğe bağlı olmamasıdır. Bir sürüm düzenlenmemiş taslaklarla kesilebiliyorsa, herkesin meşgul olduğu haftada kesilecektir. Hangi adımların makineye, hangilerinin kişiye ait olduğu <a href="https://changeloop.dev/blog/tr/changelog-automation/">changelog otomasyonu</a>'nun tamamıdır.</p> <p>Sürümü kesmek aynı zamanda bir git etiketi, bir sürüm ve bu changelog girişinin ya uyuştuğu ya da senkronizasyondan çıkmaya başladığı andır; <a href="https://changeloop.dev/blog/tr/git-tags-releases-changelog/">git etiketleri, sürümler ve changelog'unuz</a> üçünü senkronize tutmayı ele alır.</p> <h2>Üç tuzak</h2> <p><strong>Squash merge'ler footer'ları yer.</strong> Platformunuz PR başlığını mesaj olarak sıkıştırıyorsa, o branch içindeki bir commit'in <code>BREAKING CHANGE:</code> footer'ı kaybolur, ve araçlarınız sessizce breaking change'i görmeyi bırakır. Squash şablonunuzun gerçekte neyi koruduğunu kontrol edin.</p> <p><strong>Revert commit'leri hayalet girdiler üretir.</strong> Ertesi gün geri alınan bir <code>fix</code>, türetim revert'leri uzlaştırmadıkça hiç gönderilmemiş bir şey için bir girdi üretir. Çoğu araç bunu yapmaz.</p> <p><strong>Sürüm artışı ve changelog düzensizleşir.</strong> Sürüm commit'lerden hesaplanıyorsa ve changelog sonradan elle yazılıyorsa, yaklaşık iki sürümde birbirinden ayrılırlar. İkisini de aynı geçişte hesaplayın veya birinin yanlış olduğunu kabul edin.</p> <h2>Pipeline olmadan mekanik kısmı istiyorsanız</h2> <p><a href="https://changeloop.dev/changelog-generator">Changelog üreticimiz</a> türetim adımını tarayıcıda yapar: commit'leri yapıştırın, gruplandırılmış, türlendirilmiş girdiler alın. Kasıtlı olarak deterministik ve tamamen client-side'dır, bu yüzden yapıştırdığınız commit'ler makinenizi hiç terk etmez, ki bu mesajlar özel bir repodan geldiğinde önemlidir. Toplama yarısını dürüstçe yapar ve katman ikiyi denemez, çünkü katman iki bir yargıdır ve onu taklit eden bir araç tam olarak bu makalenin karşı çıktığı changelog'u üretir.</p> <p>Pipeline versiyonu için <a href="https://changeloop.dev/changelog-tools">changelog araçları</a> var olanı kapsar.</p> <h2>Özet</h2> <p>Conventional commits "bu ne tür bir değişiklik" sorusunu güvenilir ve ucuz bir şekilde cevaplar. "İnsanlara ne söylemeliyiz" sorusunu cevaplamazlar, ve commit mesajının üzerine ne kadar araç eklerseniz ekleyin bu yapmayacaktır, çünkü bilgi hiçbir zaman commit mesajında değildi. Yeniden yazım için bütçe ayırın.</p> <h2>FAQ</h2> <p><strong>Conventional commits otomatik olarak bir changelog üretir mi?</strong> Otomatik olarak bir taslak üretirler: türlendirilmiş, scope'lu, bağlantılı girdiler. Bir müşteri için ifade, gruplandırma ve neyin dışarıda bırakılacağı kararı hâlâ bir insana ihtiyaç duyar, ve o adımı atlayan bir pipeline commit mesajları yayımlar.</p> <p><strong>Hangi conventional commit türleri bir changelog'da görünür?</strong> <code>feat</code> ve <code>fix</code> her zaman, Added ve Fixed olarak. <code>perf</code> genellikle, Changed olarak. <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>build</code> ve <code>ci</code> varsayılan olarak dahilidir ve sadece bir kişi birini terfi ettirirse görünürler.</p> <p><strong>Conventional commits bir breaking change'i nasıl işaretler?</strong> Türden veya scope'tan sonra bir <code>!</code> (<code>feat(api)!: ...</code>), veya commit gövdesinde bir <code>BREAKING CHANGE:</code> footer'ı. Bir squash merge sadece PR başlığını tutarsa ikisi de kaybolur.</p> <p><strong>Bir changelog'u otomatikleştirmek için conventional commits gerekli mi?</strong> Hayır. PR etiketleri, PR şablonları ve issue bağlantıları, pull request ile merge eden ekipler için aynı metadata'yı taşır. Conventional commits, değişim birimi commit olduğunda en ucuz seçenektir.</p> </article> <article> <h1>İnsanların gerçekten okuduğu release notes nasıl yazılır</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>İnsanların okuduğu release notes yazmak için, her girdide tek bir soruyu cevaplayın: okuyucu şimdi neyi daha önce yapamadığı bir şeyi yapabiliyor, ve bunun için ne yapması gerekiyor. Bir son tarihi olan her şeyi en başa koyun, kimin etkilendiğini belirtin, doğruysa "hiçbir işlem gerekmiyor" deyin, ve söyleyecek bir şeyi olmayan sürümleri atlayın. Bu sayfadaki diğer her şey bu kuralın uygulanmasıdır.</p> <blockquote> <p>Hata düzeltmeleri ve performans iyileştirmeleri.</p> </blockquote> <p>Her ürün bunu bir kere yayımlamıştır. Sebep nadiren tembelliktir: bu, release notes içeriden, diff'te iki hafta geçirmiş ve artık hangi kısımların bir yabancının umurunda olacağını göremeyen biri tarafından yazıldığında ortaya çıkan şeydir. Daha iyi bir üslup bunu düzeltmez; soruyu cevaplamak düzeltir.</p> <h2>Release notes neleri içermeli?</h2> <p>Release notes, bahsedilmeye değer her değişiklik için şunları içermeli: okuyucunun şimdi ne yapabildiği, kimi etkilediği, ne yapması gerektiği (bu "hiçbir şey" olsa bile) ve son tarihi olan her şeyin ne zaman yürürlüğe girdiği. İç ticket numaralarını, sadece ekibin kullandığı bileşen adlarını, veya tek başlık olarak bir sürüm numarasını içermemeli.</p> <table> <thead> <tr> <th>Dahil edin</th> <th>Dışarıda bırakın</th> </tr> </thead> <tbody><tr> <td>Sonuç, okuyucunun terimleriyle</td> <td>Uygulama detayı, ekibin terimleriyle</td> </tr> <tr> <td>Kimi etkilediği, plana, role veya API sürümüne göre</td> <td>"Bazı kullanıcılar"</td> </tr> <tr> <td>Gerekli eylem, veya "hiçbir işlem gerekmiyor"</td> <td>Okuyucunun en kötü senaryoyla doldurduğu sessizlik</td> </tr> <tr> <td>Son tarihi olan her şey için bir tarih</td> <td>Tarih yerine geçen bir sürüm numarası</td> </tr> <tr> <td>Açıklayan dokümana bir link</td> <td>Pull request'e bir link</td> </tr> <tr> <td>İnsanların bildirdiği hatalar ve yükseltilen sınır</td> <td>Dahili ticket id'leri</td> </tr> <tr> <td>Sıkıcı bölüm, her biri bir satır, en altta</td> <td>Haberlerle karışmış sıkıcı bölüm</td> </tr> </tbody></table> <p>Bir release note ile bir <a href="https://changeloop.dev/blog/tr/changelog-vs-release-notes/">changelog girdisi</a> arasındaki ayrım bu listeyi mümkün kılar: changelog her şeyi tutar, böylece notlar bir şeyleri dışarıda bırakabilir. Her girdi türünün açıklamalı örnekleri <a href="https://changeloop.dev/blog/tr/release-notes-examples/">release notes örnekleri</a> yazısında toplanmıştır.</p> <h2>Her girdinin cevapladığı soru</h2> <p><strong>Okuyucu şimdi daha önce yapamadığı neyi yapabiliyor, ve bunun için ne yapması gerekiyor?</strong></p> <p>Bir girdi bunu cevaplayamıyorsa, changelog'a aittir, release notes'a değil. İki yarı da önemlidir. İlk yarı değerdir. İkinci yarı ekiplerin unuttuğu, ve eksik olduğunda destek ticket'ları üreten kısımdır.</p> <p>Gerçek iş yapan ikinci yarıdan iki örnek:</p> <ul> <li>"Mevcut webhook'lar 1 Kasım'a kadar çalışmaya devam edecek. Bu tarihten sonra imzasız payload'lar reddedilecek."</li> <li>"Hiçbir işlem gerekmiyor. Mevcut exportlar bir sonraki açışınızda otomatik olarak yeniden kodlanacak."</li> </ul> <p>İkincisi açıkça "hiçbir işlem gerekmiyor" diyor. Bu cümle her seferinde yazılmaya değer, çünkü onu bulamayan bir okuyucu en kötüsünü varsayar.</p> <h2>Release notes nasıl sıralanmalı?</h2> <p>Onları okuyucu için sonuca göre sıralayın, asla değişen sistem parçasına göre değil. API, panel, mobil ve altyapıya göre gruplamak sizin organizasyon şemanızdır, okuyucunun sorunu değil.</p> <ol> <li><strong>Breaking change'ler ve son tarihi olan her şey.</strong> Küçük olsa bile her zaman ilk sırada. Bir okuyucu bir satırdan sonra okumayı bırakırsa, bu okumuş olması gereken satırdır. Son tarih bir sunset ise, girdi bir <a href="https://changeloop.dev/blog/tr/api-deprecation/">deprecation bildirimi</a> gibi okunmalıdır.</li> <li><strong>İsteyecekleri yeni şeyler.</strong> Her paragrafa bir tane, sonuç ilk cümlede.</li> <li><strong>İyileşen şeyler.</strong> Bildirilen hatalar, yükseltilen sınırlar, yavaş olan şeyler.</li> <li><strong>Diğer her şey, liste olarak.</strong> Bağımlılık güncellemeleri, dahili refactor'lar, küçük metin değişiklikleri. Her biri bir satır. Bu bölümü kimse okumaz, ve yine de orada olmalı, çünkü onu arayan kişi gerçekten ihtiyaç duyar.</li> </ol> <h2>Yeniden yazım</h2> <p>Önce:</p> <blockquote> <p><strong>v4.2.0</strong> <code>POST /exports</code> endpoint'inin yük altında ara sıra 500 döndürdüğü sorun düzeltildi. Export worker'ı refactor edildi. <code>node-pg</code> 8.11'e güncellendi. CSV serializer'daki hata yönetimi iyileştirildi.</p> </blockquote> <p>Sonra:</p> <blockquote> <p><strong>Exportlar artık büyük hesaplarda başarısız olmuyor.</strong> Yaklaşık 50.000 satırdan fazla olan hesaplar, ay sonuna doğru daha sık olmak üzere, bir export başlatırken 500 alabiliyordu. Bu düzeltildi, ve artık her boyuttaki export başarısız olmak yerine kendini yeniden dener. Hiçbir işlem gerekmiyor, ve geçen hafta başarısız olan herhangi bir export basitçe yeniden çalıştırılabilir.</p> <p>4.2.0'da ayrıca: <code>node-pg</code> 8.11, CSV serializer'da daha net hatalar.</p> </blockquote> <p>Aynı sürüm. İkincisi etkilenen hesabı, en kötü olduğu zamanı, neyin değiştiğini ve ne yapılacağını belirtiyor. Bağımlılık güncellemesi kaybolmadı, sadece başlık olmaktan çıktı. <a href="https://changeloop.dev/blog/tr/release-notes-best-practices/">Release notes en iyi uygulamaları</a> makalesi bu yeniden yazımın izlediği kuralların geri kalanına sahip, her birinin atlanma maliyetiyle birlikte.</p> <h2>Silinmeye değer şeyler</h2> <ul> <li><strong>"Duyurmaktan heyecan duyuyoruz."</strong> Okuyucu henüz heyecanlı değil. Bunu bir sonraki cümlede kazanın.</li> <li><strong>Dahili ticket numaraları.</strong> <code>PROJ-4471</code> sizin tracker'ınızın dışında hiçbir anlam ifade etmez. Girdinin bir referansa ihtiyacı varsa, doküman sayfasına link verin.</li> <li><strong>Sadece ekibinizin kullandığı bileşen adları.</strong> "Ingest pipeline"ı yeniden adlandırdıysanız, "import'lar" deyin.</li> <li><strong>Tek başlık olarak bir sürüm numarası.</strong> <code>v4.2.0</code> bir arşivleme etiketidir, özet değil.</li> <li><strong>Kimsenin ziyaret etmediği bir ayarlar sayfasının ekran görüntüleri.</strong> Değişen şeyi kullanımda gösterin.</li> </ul> <h2>Release notes ne sıklıkla yayımlanmalı?</h2> <p>Bir şeyler olduğunda yayımlayın, bir programa göre değil. Her sürümde gelen notlar herkese onları görmezden gelmeyi öğretir. Bir şeyler olduğunda gelen notlar açılır. Hiç notu olmayan bir sürüm yayımlamak ve girdilerini okunmaya değer bir başlığa sahip bir sonraki sete devretmek uygun, ve genellikle doğrudur.</p> <p>Changelog her şeyi kaydetmeye devam eder. İş bölümü budur: changelog eksiksizdir, notlar seçicidir. Changelog'u ilerledikçe yapılandırılmış tutarsanız, notları yazmak arkeoloji yerine seçim ve yeniden yazım olur.</p> <p><a href="https://changeloop.dev/release-notes-template">Release notes şablonu</a> seçim adımı için kullandığımız formdur, ve <a href="https://changeloop.dev/changelog-examples">changelog örnekleri</a> changelog'u notlar türetmek için yeterince iyi olan ekiplerin girdilerini toplar.</p> <p>Bunların hepsi tamamen kontrol ettiğin, uzunluk sınırı olmayan ve çalışan linklere sahip bir sayfayı varsayar. <a href="https://changeloop.dev/blog/tr/mobile-app-release-notes/">Mobil uygulamalar için release notes</a> yüzey bir App Store ya da Play Store girdisi olduğunda neyin değiştiğini ele alır. <a href="https://changeloop.dev/blog/tr/emergency-release-notes/">Acil durum release notes</a> diğer istisnayı ele alır: normal yazım sürecini takip etmek için hiç zaman kalmadığında neyin değiştiğini.</p> <h2>Yayımlamadan önce bir test</h2> <p>Notları iki hafta tatilde olmuş ve 40 saniyesi olan biri gibi okuyun. O sürede kendisinden bir şey istenip istenmediğini anlayamıyorsa, notlar ne kadar doğru olursa olsun bitmemiş demektir.</p> <h2>FAQ</h2> <p><strong>Release notes ne kadar uzun olmalı?</strong> Sonuç doğuran değişikliklerin gerektirdiği kadar, bir satır fazlası değil. Bir breaking change ve iki iyileştirme içeren bir sürüm üç paragraftır. Sessiz bir sürümü önemli göstermek için doldurmak, okuyucuların notları atlamayı öğrenmesinin yoludur.</p> <p><strong>Release notes'u kim yazmalı?</strong> Değişikliği anlayan kişi, onu anlamayan biri tarafından düzenlensin. Mühendis neyin değiştiğini bilir; editör bir yabancının neyi yanlış anlayacağını bilir. Girdiyi merge anında, mühendis henüz hatırlıyorken yazmak, bunu ucuza getiren pratiktir.</p> <p><strong>Release notes hata düzeltmelerini içermeli mi?</strong> Evet, birinin bildirdiği veya karşılaştığı olanları. Sebep değil, okuyucunun gördüğü belirtiyi belirtin. "50.000 satırdan fazla exportlar başarısız oluyordu" bir okuyucunun tanıdığı bir düzeltmedir; "export worker'daki race condition düzeltildi" bir commit mesajıdır.</p> <p><strong>Release notes ile changelog arasındaki fark nedir?</strong> Changelog eksiksiz, sürekli kayıttır; release notes bir sürüm hakkındaki, henüz ilgilenip ilgilenmeyeceğine karar vermemiş insanlar için yazılmış özenle seçilmiş mesajdır. Daha uzun cevap <a href="https://changeloop.dev/blog/tr/changelog-vs-release-notes/">changelog vs release notes</a> içindedir.</p> </article> <article> <h1>Keep a Changelog, gerçekten uygulandı</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Keep a Changelog, bir <code>CHANGELOG.md</code> için tek sayfalık bir konvansiyondur: en yeni sürüm önce, bir numara ve ISO tarihi olan sürüm başına bir bölüm, altı tür (Added, Changed, Deprecated, Removed, Fixed, Security) altında gruplanmış girdiler, ve sürümler arasındaki girdiler için en üstte bir Unreleased bölümü. Ondan bahseden çoğu ekip yaklaşık üçte ikisini uygular, ve bıraktıkları üçte biri kullanıcılarını koruyan üçte birdir.</p> <p>Olivier Lacan, <a href="https://keepachangelog.com/">Keep a Changelog</a>'u 2014'te çoğu yazılım yazısından daha iyi yaşlanmış bir cümleyle yayımladı: <em>don't let your friends dump git logs into changelogs</em>. On yıl sonra, yazılımın bu köşesinin bir standarda en yakın olduğu şeydir. Bir özet yerine kaynağı okumak değerlidir; bu makale bırakılan kısımlarla ilgilidir.</p> <h2>Keep a Changelog ne ister?</h2> <p>Repo kökünde bir <code>CHANGELOG.md</code>, en yeniden başlayarak, sürüm başına bir bölüm ile. Her sürüm bir numara ve ISO tarihi taşır, ve girdilerini altı tür altında gruplandırır:</p> <table> <thead> <tr> <th>Tür</th> <th>Ne için</th> <th>Bırakmanın maliyeti</th> </tr> </thead> <tbody><tr> <td>Added</td> <td>Yeni özellikler</td> <td>Hiçbir şey; kimse bunu bırakmaz</td> </tr> <tr> <td>Changed</td> <td>Mevcut davranıştaki değişiklikler</td> <td>Okuyucular davranış değişikliğini bir hatadan öğrenir</td> </tr> <tr> <td>Deprecated</td> <td>Kaldırılmak üzere olan özellikler</td> <td>Bir kaldırma, planlı bir olay yerine bir olay haline gelir</td> </tr> <tr> <td>Removed</td> <td>Bu sürümde kaldırılan özellikler</td> <td>Kimse bir kaldırmayı bir hatadan ayıramaz</td> </tr> <tr> <td>Fixed</td> <td>Hata düzeltmeleri</td> <td>Hiçbir şey; kimse bunu da bırakmaz</td> </tr> <tr> <td>Security</td> <td>Güvenlik açıkları</td> <td>Onu arayan tek okuyucu bulamaz</td> </tr> </tbody></table> <p>Artı en üstte bir <code>Unreleased</code> bölümü, böylece bir girdi merge edildiği anda konulacak bir yer olur, ve herkes neyin geldiğini görebilir.</p> <p>Bu neredeyse hepsi. Geri kalanı gerekçedir: girdiler insanlar içindir, değişiklik başına bir girdi, ve dosya bir günlük yerine bir belgedir.</p> <h2>Keep a Changelog'un hangi bölümleri bırakılır?</h2> <p>Unreleased bölümü, ardından altı türün dördü, Security de aralarında, bu sırayla.</p> <p><strong><code>Unreleased</code> önce ortadan kalkar.</strong> Son tarihi olmayan bölümdür, bu yüzden bakımı ilk duran bölümdür, ve gittiğinde girdiler sürüm zamanında commit geçmişinden yazılır. Bu, spesifikasyonun en başta uyardığı git-log-dump'ın tam olarak kendisidir, kademeli olarak ulaşılmış. <a href="https://changeloop.dev/blog/tr/changelog-automation/">Changelog otomasyonu</a> çoğunlukla bu bölümü kimsenin hatırlamasına gerek kalmadan canlı tutmakla ilgilidir.</p> <p><strong>Altı tür ikiye çöker.</strong> Çoğu gerçek changelog Added ve Fixed ile sonuçlanır, çünkü Changed ve Deprecated birinin neye güvendiği hakkında bir yargı gerektirir. Bu yargı değerli olan kısımdır. Deprecated özellikle gelecek hakkında bir söz olan tek türdür, ve onu bırakmak bir kaldırmanın nasıl bir olaya dönüştüğüdür; o sözü tutmanın mekanizması <a href="https://changeloop.dev/blog/tr/api-deprecation/">bir API nasıl deprecate edilir</a> içindedir.</p> <p><strong>Security ayrı olmaktan çıkar.</strong> Fixed altında dosyalanmış bir güvenlik düzeltmesi, onu arayan tek okuyucu için görünmezdir. Düzeltme önemsiz olsa bile onu ayrı tutun, ve özellikle ona dikkat çekmeyi tercih etmediğinizde.</p> <h2>Spesifikasyon neyi cevaplamaz?</h2> <p>Bu bir dosya formatıdır. Onu benimsedikten hemen sonra karşılaşacağınız sorular hakkında hiçbir şey söylemez:</p> <ul> <li><strong>Bunu kim nasıl öğrenir?</strong> Bir repo'daki bir dosya katkıda bulunanlara ulaşır. Hiç GitHub açmamış bir müşteriye ulaşmaz.</li> <li><strong>Sürümü olmayan ürünler ne olacak?</strong> Sürekli dağıtılan bir hizmetin gruplayacak bir v4.2.0'ı yoktur. Çoğu ekip bunun yerine tarihleri kullanır, ki bu işe yarar, ve spesifikasyon bunu ne onaylar ne de yasaklar.</li> <li><strong>Girdiyi kim yazar?</strong> Spesifikasyon bir insanın yaptığını varsayar. Ne zaman yapacağını söylemez.</li> <li><strong>Birden çok hedef kitle ne olacak?</strong> Bir dosya geliştiricilere hizmet eder. Aynı içeriği teknik olmayan bir yöneticiye hizmet etmez, ve onun için elle yeniden biçimlendirmek çoğaltmanın başladığı yerdir. <a href="https://changeloop.dev/blog/tr/changelog-vs-release-notes/">Changelog vs release notes</a> spesifikasyonun size kendinize bıraktığı bölünmedir.</li> </ul> <p>Fikrin daha katı bir çatalı olan <a href="https://common-changelog.org/">Common Changelog</a>, bunun bir kısmını sıkılaştırır: belirli girdi ifadelerini yasaklar, değişikliğe bir bağlantı gerektirir, ve okuyucunun kim olduğu konusunda net bir görüşe sahiptir. Keep a Changelog'un gevşek kısımları ekibinizin sürekli tartıştığı şeyse okumaya değer.</p> <h2>Keep a Changelog git loglarını dökmeden otomatikleştirilebilir mi?</h2> <p>Evet: taslağı yapılandırılmış commit'lerden türetin, türü önceden doldurulmuş olarak Unreleased'e koyun, ve bir sürüm kesilmeden önce bir insanın ifadeyi düzenlemesini zorunlu kılın. Spesifikasyonun uyarısı çıktı hakkındadır, araç hakkında değil. Commit'lerden bir taslak türetmek sorun değil. O taslağı düzenlenmemiş olarak yayımlamak karşı çıktığı şeydir.</p> <p>Makine, iyi olduğu toplama ve biçimlendirmeyi halleder. İnsan, iyi olmadığı seçim ve ifadeyi halleder. <a href="https://changeloop.dev/blog/tr/conventional-commits-changelog/">Conventional commits</a>, bunun dayandığı iki katmanlı ayrımı ve hangi commit türlerinin yukarıdaki altı kategoriden hangisine karşılık geldiğini anlatır. <a href="https://changeloop.dev/changelog-tools">Changelog araçları</a> özetimiz toplama yarısı için var olanı kapsar.</p> <h2>Keep a Changelog nerede yetersiz kalmaya başlar?</h2> <p>Dağıtımda durur. Keep a Changelog, "bu dosya nasıl görünmeli" sorusuna iyi bir cevaptır. "Kullanıcılarımız neyin değiştiğini nasıl öğrenir" sorusuna bir cevap değildir, çünkü bir repo'daki bir Markdown dosyası, sadece kullanıcılarınız katkıda bulunanlarsa işe yarayan bir dağıtım stratejisidir.</p> <p>Bu, çoğu ekibin ikinci karşılaştığı engeldir: dosya iyi durumda, ve ekip dışında kimse onu okumuyor. Bunu çözmek, girdilerin başka bir yerde görselleştirilebilecek verilere dönüşmesi anlamına gelir, ki bu bir dosyayı biçimlendirmekten farklı bir sorundur, ve <a href="https://changeloop.dev/changelog-examples">changelog örnekleri</a>'nin repo dosyaları yerine genel changelog sayfaları toplamasının sebebidir. O girdileri insanların geri döndüğü bir şeye dönüştürmek, <a href="https://changeloop.dev/blog/tr/changelog-page/">bir changelog sayfası nasıl kurulur</a>'da ele alınır.</p> <p>Yine de spesifikasyonu benimseyin. Bir öğleden sonra sürer, ikinci sorunu ele alınabilir hale getirir, ve bu konuda yazılmış hâlâ en iyi tek sayfadır.</p> <h2>FAQ</h2> <p><strong>Keep a Changelog bir standart mı?</strong> Geniş bir kabul gören bir konvansiyondur, bir standardizasyon kuruluşunun spesifikasyonu değildir. Araçlar (sürüm scriptleri, linter'lar, parser'lar) şeklini o kadar sık varsayar ki onu takip etmek uyumluluk satın alır.</p> <p><strong>Unreleased bölümüne ne girer?</strong> Merge edilmiş ancak numaralı bir sürümde henüz gönderilmemiş bir değişiklik için her girdi. Bir sürüm kesildiğinde, bölüm sürüm ve tarih olarak yeniden adlandırılır, ve üstüne yeni, boş bir Unreleased bölümü gelir.</p> <p><strong>Bir changelog semantik versiyonlama kullanmalı mı?</strong> Keep a Changelog bunu önerir ve zorunlu kılmaz. Kütüphaneler ve API'ler bundan faydalanır; sürekli dağıtılan bir hizmet genellikle tarihleri kullanır, ki format buna izin verir.</p> <p><strong>Güvenlik düzeltmeleri kamuya açılmadan önce changelog'da olmalı mı?</strong> Girdiyi düzeltme gönderildiğinde ekleyin, bir operatörün harekete geçmesine yetecek kadar detayla, daha fazlasıyla değil. Girdiyi koordine bir açıklama tarihine kadar ertelemek normaldir; onu atlamak değildir.</p> </article> <article> <h1>Değer verilen release notes en iyi uygulamaları</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Önemli olan release notes en iyi uygulamaları, bir sonucu olanlardır: girdiyi merge anında yazın, kimin etkilendiğini belirtin, gerekli eylemi hiç olmasa bile belirtin, breaking change'lere tarih verin, değişiklik başına bir kalıcı girdi tutun, sonuca göre gruplayın, ve sıkıcı bölümü koruyun. Her biri okuyucunun ne yaptığını değiştirir. Bu konudaki diğer tavsiyelerin çoğu notların nasıl göründüğünü değiştirir.</p> <p>Release notes en iyi uygulamaları arayın ve stil tavsiyesi bulun: net olun, öz olun, sade dil kullanın, ekran görüntüleri ekleyin. Bunların hiçbiri yanlış değil ve hiçbiri hiçbir şeyi değiştirmiyor, çünkü hiçbir ekip belirsiz olma niyetiyle oturmamıştır. Aşağıdaki uygulamalar atlamanın maliyetiyle birlikte gelir, çünkü ekli bir başarısızlık modu olmayan bir uygulama sadece bir tercihtir.</p> <table> <thead> <tr> <th>Uygulama</th> <th>Atlamanın maliyeti</th> </tr> </thead> <tbody><tr> <td>Girdiyi release'te değil merge'de yazmak</td> <td>Sonradan yeniden oluşturulan girdiler "çeşitli iyileştirmeler" der</td> </tr> <tr> <td>Kimin etkilendiğini belirtmek</td> <td>Her okuyucu bunun kendisini ilgilendirmediğine karar verir</td> </tr> <tr> <td>Gerekli eylemi belirtmek, "hiçbiri" dahil</td> <td>Kırk aynı destek ticket'ı, ve en kötüsünü varsayan okuyucular</td> </tr> <tr> <td>Breaking change'lere tarih vermek, versiyonlamak değil</td> <td>Son tarih geçtikten sonra keşfedilir</td> </tr> <tr> <td>Değişiklik başına kalıcı, bağlanabilir bir girdi</td> <td>Kimse "bu ne zaman değişti" diye cevap veremez</td> </tr> <tr> <td>Sisteme göre değil sonuca göre gruplamak</td> <td>Okuyucular kendi bölümlerini bulmak için mimarinizi bilmek zorunda kalır</td> </tr> <tr> <td>Sıkıcı bölümü korumak</td> <td>Güvenlik, uyumluluk ve sürüm uyuşmazlığı hata ayıklayan kişi kaynaklarını kaybeder</td> </tr> </tbody></table> <h2>Release notes için en iyi uygulamalar nelerdir?</h2> <p><strong>Girdiyi merge ettiğinizde yazın, yayımladığınızda değil.</strong> Atlamanın maliyeti: sürümü commit geçmişinden yeniden oluşturan kişi değişikliği yapan kişi değildir, ve niyeti tahmin edecektir. İki hafta sonra yazılan girdiler "çeşitli iyileştirmeler" diyenlerdir.</p> <p><strong>Kimin etkilendiğini isimle belirtin.</strong> "Business plandaki ekipler", "v1 export API'sini kullanan herkes", "Postgres 14'te self-hosted kurulumlar". Atlamanın maliyeti: her okuyucu kendisini ilgilendirip ilgilendirmediğini anlamak zorunda kalır, ve çoğu ilgilendirmediğine karar verir.</p> <p><strong>Gerekli eylemi, hiç olmasa bile belirtin.</strong> Atlamanın maliyeti: destek aynı soruyu kırk kez cevaplar, ve sormayan okuyucular bir şey gerektiğini varsayıp erteler.</p> <p><strong>Breaking change'lere sürüm numarası değil tarih verin.</strong> "v5'te kaldırıldı" v5'in ne zaman geleceğini bilmeyen biri için hiçbir şey ifade etmez. "1 Kasım'da çalışmayı bırakır" herkes için aynı şeyi ifade eder. Atlamanın maliyeti: son tarih geçtikten sonra keşfedilir. Neyin buna dahil olduğu ve onu yayımlamak için kontrol listesi <a href="https://changeloop.dev/blog/tr/breaking-changes/">breaking change nedir</a> içindedir.</p> <p><strong>Değişiklik başına kalıcı, bağlanabilir bir girdi tutun.</strong> Bir e-posta arşiv değildir ve bir Slack mesajı referans değildir. Atlamanın maliyeti: altı ay sonra kimse "bu ne zaman değişti" diye cevap veremez, siz de dahil. E-postanın yine de bir işi var, <a href="https://changeloop.dev/blog/tr/product-update-email/">ürün güncellemesi e-posta şablonu</a>'nda ele alınan; kaydı değiştirmek yerine ona işaret eder.</p> <p><strong>Sisteme göre değil sonuca göre gruplayın.</strong> Atlamanın maliyeti: okuyucu hangi bölümün onu ilgilendirdiğini anlamak için mimarinizi kafasında tutmak zorunda kalır. Bundan çıkan sıralama <a href="https://changeloop.dev/blog/tr/how-to-write-release-notes/">release notes nasıl yazılır</a> içindedir.</p> <p><strong>Sıkıcı bölümü koruyun.</strong> Bağımlılık güncellemeleri ve dahili değişiklikler en altta kalır, her biri bir satır. Atlamanın maliyeti: güvenlik ekibi, uyumluluk incelemecisi ve sürüm uyuşmazlığı hata ayıklayan kişi tek kaynaklarını kaybeder. Bunu en sık yanlış yapan girdiler düzeltmelerdir; <a href="https://changeloop.dev/blog/tr/bug-fix-release-notes/">hata düzeltmesi release notes</a> onları, okuyucu harekete geçip geçmeyeceğini bilecek şekilde nasıl yazacağınızı gösterir.</p> <h2>Changelog en iyi uygulamaları nelerdir, ve nasıl farklıdır?</h2> <p>Bir changelog bir referanstır, bu yüzden uygulamaları ikna etmek yerine eksiksizlik ve yapı ile ilgilidir. Önemli olan dört tanesi:</p> <ul> <li><strong>Satır başına sabit bir girdi türü.</strong> Added, Changed, Deprecated, Removed, Fixed, Security. Bir ev stili değil, bir filtre: "sadece breaking change'leri" istemeyi mümkün kılan şeydir. <a href="https://changeloop.dev/blog/tr/keep-a-changelog-implemented/">Keep a Changelog</a> konvansiyonu genellikle bunun kaynağıdır.</li> <li><strong>Yayımlanmamış bölüm.</strong> Girdilerin merge ile release arasında yaşadığı yer. Yokluğu ekiplerin girdileri geç yazmasının sebebidir.</li> <li><strong>ISO tarihleri.</strong> <code>2026-08-28</code>, <code>28/08/26</code> değil, çünkü ikincisi okuyucuya göre iki farklı gün anlamına gelir.</li> <li><strong>Commit başına değil değişiklik başına bir girdi.</strong> Bir hatayı düzelten üç commit bir girdidir.</li> </ul> <p>İki artefakt <a href="https://changeloop.dev/blog/tr/changelog-vs-release-notes/">changelog vs release notes</a> içinde detaylıca karşılaştırılır; kısa versiyon changelog'un uygulamalarının eksiksizliği, release notes'un uygulamalarının ise dikkati koruduğudur. <a href="https://changeloop.dev/blog/tr/private-release-notes-enterprise/">Kurumsal müşteriler için özel release notes</a> bunun sadece müşterileriniz artık hepsi aynı build üzerinde olmadığında ortaya çıkan bir versiyonunu ele alır: aynı eksiksizlik ve dikkat hedefleri, ama hepsine aynı anda yayınlanmak yerine hesap başına ayarlanmış.</p> <h2>Kargo kültü olan üç şey</h2> <p><strong>Girdi türü olarak emoji.</strong> Bir roket ve bir İngiliz anahtarı bir taksonomi değildir. Düzenli görünürler ve faydalı bir şekilde filtrelenemezler, sıralanamazlar, veya bir ekran okuyucu tarafından okunamazlar. Kelimeler kullanın, ve emoji istiyorsanız, kelimeden sonra koyun.</p> <p><strong>Barındırılan bir ürün için başlık olarak semantik sürüm numaraları.</strong> Semver, API uyumluluğu hakkında bir sözdür. Kimsenin sürümünü seçmediği bir SaaS ürünü için, başlıktaki bir sürüm numarası haber gibi giydirilmiş dahili arşivlemedir. Semver'i changelog'da tutun ve duyurunun dışında.</p> <p><strong>İçeriğe bakılmaksızın bir programa göre yayımlamak.</strong> İçinde bir şey olmayan aylık notlar insanlara notlarınızın gürültü olduğunu öğretir. Söyleyecek bir şey olduğunda yayımlayın. Changelog geri kalanını kapsar.</p> <h2>Gerçekten zor olan tek şey</h2> <p>Changelog ve duyuruyu her şeyi iki kez yazmadan senkronize tutmak.</p> <p>Çoğu ekip tek bir sayfayla başlar, hedef kitleler farklılaştığında onu böler, ve sonra sessizce ikisinden birinin çürümesine izin verir, genellikle changelog'un, çünkü ona bağlı bir son tarih yoktur. Çıkış disiplin değil yapıdır: girdileri bir tür, tarih ve hedef kitle ile veri olarak tutun, ve her iki yüzeyi de bunun görselleştirmeleri olarak ele alın. <a href="https://changeloop.dev/changelog-tools">Changelog araçları</a> özetimiz bunun için ne olduğunu, rekabet ettiğimiz araçlar dahil, kapsar, ve <a href="https://changeloop.dev/beamer-alternative">Beamer alternatifi</a> sayfası çoğu ekibin başladığı widget'a karşı dürüst karşılaştırmadır.</p> <p><a href="https://changeloop.dev/release-notes-template">Release notes şablonu</a> girdiler var olduğunda seçim adımının yaşadığı yerdir.</p> <h2>Yalnızca birini benimseyecekseniz</h2> <p>Girdiyi merge anında, sabit bir formatta, bir türle yazın. Bu sayfadaki diğer her uygulama bu yerine oturduğunda kolaylaşır, ve hiçbiri onsuz hayatta kalmaz.</p> <h2>FAQ</h2> <p><strong>Release notes ekran görüntüleri içermeli mi?</strong> Sadece değişen şeyin kullanımda olduğu ekran görüntüleri. Kimsenin ziyaret etmediği bir ayarlar sayfasının ekran görüntüsü kaydırma ekler, bilgi eklemez. Sonucu ve etkilenen okuyucuyu belirten metin, ikisini de göstermeyen bir görüntüyü yener.</p> <p><strong>Bir breaking change için release notes nasıl yazılır?</strong> Önce tarih, sonra etkilenen çağıranlar, sonra gerekli eylem, sonra göç. Asla sürüm numarasıyla başlamayın. Örnek bir girdiyle tam form <a href="https://changeloop.dev/blog/tr/breaking-changes/">breaking change nedir</a> içindedir.</p> <p><strong>Release notes mühendislik mi pazarlama tarafından mı yazılmalı?</strong> Değişikliği yapan mühendis tarafından, merge anında hazırlanır, ve onu yabancı gibi okuyan biri tarafından düzenlenir. İkisinden hiçbiri tek başına bir müşterinin harekete geçebileceği notlar üretmez.</p> <p><strong>İdeal release notes formatı nedir?</strong> Önce son tarihi olan öğeler, sonra yeni yetenekler, sonra iyileştirmeler, sonra geri kalanı için her biri bir satır olan bir liste. <a href="https://changeloop.dev/release-notes-template">Release notes şablonu</a> bu formatın doldurulacak bir sayfa halidir.</p> </article> </main></body></html>