Bilerek Kırıcı Bir Değişiklik Yayımladık ve Kendi Dokümanlarımız Hâlâ Eski Alan Adlarını Öğretiyor

Aşağıdaki dokümantasyon kusuru canlıdır, bizimdir ve bu sayfayı yazarken bulduk.

Süsleme olmayan bir sürüm artışı

Kimlik bilgisi veri modeli bir ana sürümden diğerine geçti ve değişiklikler arasında, bir kimlik bilgisinin ne zaman geçerli olduğunu anlatan alan adları vardı.

Eski sürüm belge dilinden ödünç alınmış adlar kullanıyordu: ne zaman ihraç edildiği, ne zaman sona ereceği. Yeni sürüm geçerliliği doğrudan anlatan adlar kullanıyor: şu tarihten itibaren geçerli, şu tarihe kadar geçerli.

İki alanı yeniden adlandırmak kırıcı bir değişikliktir, çünkü eski adları okuyan her tüketici, yeni adları taşıyan bir kimlik bilgisinden hiçbir şey alamaz. Hata yok, uyarı yok. Eksik bir değer.

Kırılmayı neden ikisini birden desteklemek yerine göze aldık

İki kümeyi de yayarak herkesi memnun edebilirdik. Birkaç uygulama tam olarak bunu yaptı.

Yapmadık, iki sebeple.

Avrupa çerçevesi yeni modeli işaret ediyor. Eski alan adlarını taşıyan bir kimlik bilgisi, inşa etmeye çalıştığımız gereksinimi karşılamayan bir kimlik bilgisidir ve ikisini birden taşımak, hiçbir zaman tam olarak karar vermemenin bir yoludur.

Ve ikisini birden desteklemek maliyeti kaldırmaz, gizler. Kullanımdan kaldırılmış adlara göre inşa edilmiş tüketiciler çalışmayı sürdürür, dolayısıyla kimse geçiş yapmaz ve kırılma daha sonra, arkasında daha çok kodla gelir. Kırıcı bir değişikliği erken almak, geç almaktan ucuzdur, insanlara söylemeniz koşuluyla.

Başarısız olduğumuz yer o son cümledir.

Yanlış yaptığımız kısım

Kendi geliştirici dokümantasyonumuz hâlâ eski alan adlarını gösteriyor.

Kimlik bilgilerini bir geliştiriciye anlatan sayfa baştan sona kullanımdan kaldırılmış adları kullanıyor, güncel olanları ise hiç kullanmıyor. Onu takip eden bir geliştirici, yazılımımızın yaymadığı bir alanı okuyan kod yazar ve tamamen geçerli bir kimlik bilgisinden tanımsız bir değer alır.

Bu, güncelliğini yitirmiş bir sayfadan kötüdür. Canlı bir yüzeyde, bozuk kod üreten ve nedenine dair hiçbir sinyal vermeyen bir talimattır.

Bunu bu makaleyi yazarken bulduk, kendi dokümantasyonumuzu paketlerin gerçekte yayımladığı tip tanımlarına karşı kontrol ederek. Tipler doğru. Dokümantasyon değil.

Bunu neden bir pazarlama sayfasına koyuyoruz

Çünkü bir dokümantasyon kusuru, tam olarak bir satıcının sessizce düzeltip hiç söz etmediği türden bir şeydir ve sessiz düzeltmeler örüntüsü, bir projenin açık iddialarını güvenilmez kılan şeydir.

Kırıcı bir değişiklik ancak geçiş yolu görünürse savunulabilirdir. Kırılmayı savunulabilir bir sebeple aldık ve sonra bunun en çok okunan açıklamasını yanlış yönü gösterir hâlde bıraktık, ki bu iyi bir kararı kötü bir geliştirici deneyimine çevirir.

Bunu yayımlamak bize bir şeye mal oluyor ve bu sitenin geri kalanıyla tutarlı olan tek sürüm bu.

Entegre ediyorsanız bu ne demek

Düzyazı yerine tip tanımlarını okuyun. Tipler kodun yaptığından üretilir; düzyazı birinin o zaman anladığından üretilir.

Bu bir mazeret değil, genel bir tavsiyedir. Bir satıcının dokümantasyonu ile tipleri anlaşmazlığa düştüğünde, ürün tiplerdir ve iki kaynağı birbiriyle çelişen bir satıcı size sürüm süreci hakkında bir şey söylemiştir, bizimki dahil.

Herhangi bir kimlik bilgisi satıcısına sorulacaklar

"Veri modelinin hangi sürümünü yayıyorsunuz ve ikisini birden mi yayıyorsunuz?" İkisini birden yaymak meşru bir tercihtir ve bir kaza değil, belirtilmiş bir tercih olmalıdır.

"Dokümanlarınız ile tip tanımlarınız birbiriyle uyuşuyor mu?" Siz beklerken kontrol etmelerini isteyin. Bizde, bu sayfa itibarıyla, uyuşmuyor.

"Geçiş yaptığınızda ne bozuldu ve insanlara nasıl söylediniz?" Bu alanda hiç kırıcı değişiklik almamış bir satıcı, muhtemelen standartla birlikte hareket etmemiştir.

"Sürümler arasındaki alan adı eşlemesi nerede?" Yoksa, her entegratör onu yeniden keşfeder.

Bu karar için ne anlama geliyor

Bugün entegre ediyorsanız, güncel alan adlarını kullanın, onları yayımlanan tiplerden alın ve o dokümantasyon sayfasını değişene kadar yanlış kabul edin.

Bir satıcının standart hareketini nasıl yönettiğini değerlendiriyorsanız, işe yarayan sinyal dokümanlarımızın kaymış olması değildir, çünkü çoğu kayar. Kaymanın, sayfası adıyla belirtilerek açıklanıp açıklanmadığıdır, ki bu paragraf tam olarak odur.