RFC'den ADR'ye: Karara Ulaşmak ve Gerekçeyi Korumak

Hiç kimsenin yeniden oluşturamadığı karar

Yeni teknoloji lideri makul bir soru soruyor: her hizmet neden o kuyruk aracılığıyla faturalama sistemiyle iletişim kuruyor? Bir ADR var — ADR-014, dört cümle, on bir ay önce yazılmış. Bağlam: "güvenilir faturalama entegrasyonuna ihtiyacımız vardı." Karar: "kuyruğu kullan." Sonuçlar: "biraz ek gecikme." Teknik olarak bir kayıt. Hiçbir şeyi yanıtlamıyor.

Oradaydın, bu yüzden ADR-014'ün söylemediğini biliyorsun: iki Slack kanalında ve hararetli bir PR dizisinde geçen üç haftalık tartışma; o zamandan beri artırılan bir hız sınırı nedeniyle kaybeden senkron-API seçeneği; şimdi kimsenin bulamadığı bir kıyaslama ile yanıtlanan personel mühendisinin itirazı. Tartışma gerçekleşti. Kayıt daha sonra, bir kişinin, bir Cuma günü, hafızasından yazıldı.

Bu, gerçekten iyi bir uygulamanın belgelenmiş, neredeyse evrensel başarısızlık modudur. AWS'nin öneri rehberi ve Microsoft'un İyi Tasarlanmış belgeleri her ikisi de ADR'leri önermektedir — ve her ikisi de acıyı belirtmektedir: güncel tutmak zaman alır ve ekipler ve seçimler arttıkça yönetmek karmaşık hale gelir. Temel neden yapısaldır: tartışma ve kayıt farklı yerlerde yaşar, bu nedenle kayıt her zaman kayıplı bir transkripsiyondur. Çözüm, bunları aynı yer haline getirmektir. Uygulama mühendislik spesifik değildir, hatta ADR spesifik de değildir. Google, önemli teknik çalışmalara başlamadan önce yazılı ve gözden geçirilmiş bir tasarım belgesi — sorun, önerilen yaklaşım, değerlendirilen alternatifler, ticaret-off'lar — gerektirir; bu, şirketin kendi Google'da Yazılım Mühendisliği belgesinde belirtilen bir uygulamadır. Bu, bir ADR ile aynı disiplindir, bir adım daha önce uygulanır: ADR, bir tasarım belgesinin savunduğu seçimi kaydeder. İkisi de aynı nedenle aynı şekilde başarısız olur ve her ikisi de aynı hareketle düzeltilir — kaydın yaşadığı yerde tartışmayı tutmak, birini diğerine sonradan transkribe etmek yerine. Aşağıdaki her adımı her iki belgeyi de kapsayacak şekilde okuyun.

Neden ADR'ler bozulur

ADR topluluğunun kendi materyalinden bir cümle tüm tanıyı taşıyor: bir RFC genellikle anlaşmaya ulaşmakla ilgilidir; bir ADR ulaşılan anlaşmayı kaydeder. İki eser, iki an — ve aralarındaki her şey sızar. "Açıkça" yanlış olan alternatifler kaydedilmez (ta ki açık olmaktan çıkana kadar). Nihai tasarımı şekillendiren itiraz, yalnızca kapalı bir başlıkta bir PR yorumu olarak hayatta kalır. Bağlam bölümü en son, en kötü şekilde, oyunu kaybeden tarafından yazılır. Karar üretmesi gereken toplantılar özetler üretir ve bir kararı kalıcı kılan akıl yürütme — tüm karar kalitesi zinciri bunun üzerine inşa edilmiştir — tam olarak transkripsiyonun düştüğü şeydir.

Adım 1–3: Teklif, bağlam, seçenekler

1. 1Öneriyi ana iddia olarak belirtin — önerilen karar, bir soru değil: "Tüm faturalama yazmalarını kalıcı bir kuyruğa yönlendireceğiz." Bu cümle gelecekteki ADR'nin başlığıdır. Kontrol noktası: kök var, bir cümle, önerici tarafından yazılmıştır.
2. 2Ayrı pro-argümanlar olarak bağlam. Karar almayı gerekli kılan her bir güç — güvenilirlik gereksinimi, faturalama sistemi hız limiti, denetim yetkisi — kök altında kendi argümanıdır. Monolitik bir "Bağlam" paragrafı sorgulanamaz; üç ayrı bağlam iddiası her biri ayrı ayrı sorgulanabilir, onaylanabilir veya çürütülebilir. Kontrol Noktası: ≥2 bağlam argümanı, her biri bir güç.
3. 3Her seçenek kendi düğümünü alır. Kuyruk, senkron API, toplu iş — kardeş argümanlar, her biri kendi artı ve eksileriyle. Artı/eksi, ebeveynle ilişkilidir, bu nedenle bir seçeneğin dezavantajları o seçeneğe bağlıdır, karara değil. Reddedeceğinizi beklediğiniz seçenekleri de dahil edin: reddedilen kardeş, gelecek yılın "neden sadece… yapmadık" sorusunu yanıtlar. Kontrol noktası: bir okuyucunun sorabileceği her seçenek mevcuttur.

Adım 4–6: Kayıt bırakan RFC turu

Şimdi inceleme turu — genellikle sohbet, yorumlar ve koridorlarda dağınık bir şekilde gerçekleşen kısım. Burada, her biri bir dört döngü diyaloğu olan, bir inceleyici ile seçeneğin yazarı arasında üç tür yapılandırılmış değişim olarak yürütülüyor:

Adım 7: Karar verme — ve derecelendirmenin ne olmadığı

Karar vericiler seçenekleri değerlendirir: her birine etiketlenmiş bir puan. Dağılım, gerçek bir kanıttır — odanın durumu, kayıtlara göre, arama öncesinde. Ama puan karar değildir. Adı geçen bir insan hala karar verir ve eğer arama dağılıma karşı olursa, karar düğümü burada açıklanır. (O adı geçen insanın kim olması gerektiği ve rolün tartışmadan önce nasıl atanacağı kendi disiplini — bkz. karar hakları eğitimi.)

Adım 8–9: Yazmak zorunda olmadığınız ADR

İşte sonuç. Kayıt, sonradan yazdığınız bir belge değildir — bu, seçilen seçeneğin düğümü ve ona bağlı olan her şeydir: bağlam argümanları (Bağlam), reddedilen kardeşler (Değerlendirilen Seçenekler), tamamlanmış zincirler (tartışma, yazarlarla birlikte), derecelendirmeler (odanın durumu) ve gerekçesiyle birlikte karar argümanı (Karar). Hiçbir şey transkribe edilmez, bu nedenle transkripsiyonda hiçbir şey kaybolmaz.

1. 1Kabul ettiğiniz sonuçları kaydedin. Bilinen dezavantajlar — ek gecikme, kuyruğun operasyonel yükü — seçilen seçeneğin kabul edilen çocukları olarak devam eder. Bunları yazmak, bunu bir tercih yerine bir karar haline getirir. Kontrol Noktası: Kayıtta ≥1 kabul edilen sonuç.
2. 2Kuruluşunuzun depo izlemeli ADR'lere ihtiyacı varsa dışa aktarın. Birçoğu, doğru bir şekilde — kodun yanındaki markdown ADR, uyum belgesi olarak kalır. Ağaçtan dört bölümlü özeti yazın (beş dakika, Cuma değil), tam tartışma için geri bağlantı verin. Kontrol noktası: depo ADR, ağacı belirtir; ağaç, gerekçeyi tutar.

Aynı fikirde olmamak ve taahhüt etmek, kayıtlara geçmek üzere

Amazon'un ünlü yaptığı model — karşı çık ve taahhüt et — bir okunabilirlik sorunu var: Birisi daha sonra karşı çıkmanın gerçek, duyulmuş ve yanıtlanmış olduğunu nasıl bilebilir, yoksa üstünden geçilmiş mi? Zincir mekanikleri buna yanıt veriyor. Dört tam turunu tamamlayan ve anlaşma olmadan sona eren bir İnceleme zinciri tam olarak bu kayıttır: itiraz yapıldı, yanıtlandı, ısrar edildi ve tekrar yanıtlandı, kayıtlara geçildi, muhalif taahhüt etmeden önce. Muhalifin duyulduğu belgelenmiştir — bu da sonrasında taahhüt etmenin makul olmasını sağlar, sadece itaatkar olmaktan ziyade.

Adım 10: Silmeden geçersiz kılma

Kararların yaşı. Senkron seçeneği öldüren hız sınırı yükseldiğinde, doğru hamle, yerini aldığına atıfta bulunan yeni bir karar vermektir — ADR-014'ün düğümüne bağlı yeni bir argüman, neyin değiştiğini belirtir. Eski karar okunabilir kalır; gerekçesi, yeni kararın neyi geçersiz kıldığını bilmesinin tam nedenidir.

Yönetilmesi gereken bir dürüst boşluk: yerleşik bir ADR durum alanı yoktur. Önerilen / kabul edilen / geçersiz kılınan bir argümanda birinci sınıf bir durum değildir — geçersizlik, bağlantı ile modellenir ve bu konvansiyonu sürdürmek sizin sorumluluğunuzdadır. Bunu ürünün bunu zorunlu kıldığını varsaymak yerine, ekibinizin çalışma anlaşmasında belirtin.

Dürüst sınırlamalar

• ✗Bu, repo'nuzdaki ADR'lerin yerini almaz eğer organizasyonunuz bunların kodla birlikte versiyon kontrolünde olmasını gerektiriyorsa. Özeti dışa aktarın ve taahhüt edin; tartışma için markdown'un zayıf olduğu kısım için ağaç yapısını kullanın.
• ✗ADR durumu alanı yok. Önerilen/kabul edilen/iptal edilen, ürünün zorunlu kıldığı bir şey değil, sizin sürdürdüğünüz bir bağlantı kuralıdır.
• ✗Bir zincir dört dönüşten oluşur. Derin mimari anlaşmazlık bir çağrı gerektirecektir; zincir, daha önce denenmiş olanların kaydıdır.
• ✗Değerlendirmeler tek etiketli bir değerdir, ağırlıklı çok kriterli puanlama değildir.
• ✗Hiç kimseyi iyi bir bağlam yazmaya zorlamaz. Yapı, iyi bir kaydın maliyetini düşürür; yargıyı sağlamaz.

Pratik dersler

• ✓Bir RFC, bir tartışma. Tüm çeyrek mimarisini kaplayan mega-ağaçla direnin — üstlenme bağlantıları, kararları iç içe geçmekten daha iyi bağlar.
• ✓Mevcut olandan tohum al. Karar ağırlıklı bir transkript veya eski ADR klasörünüz, çıkarıldığında tartışmaya hızlı bir başlangıç sağlar — ithal olarak etiketlendiği için canlı argümanlar ayırt edilebilir kalır.
• ✓Değerlendiricilerin isimlerini zincirlerine koyun ve orada bırakın. Atıf, sorumluluktur; anonim mimari itirazlar folklora dönüşür.
• ✓Sonuçlar bölümü karar verene aittir, başkasına değil. Kabul edilen olumsuzluklar, onları kabul eden kişi tarafından yazıldığında, bir inceleyicinin uyarılarından farklı bir ağırlığa sahiptir.

ADR-014, yanıt veren versiyon

Yeni teknoloji liderinin sorusuna geri dönelim. Yeniden inşa edilen versiyonda, ADR-014 bir düğüm: gerekçesiyle birlikte kuyruk kararı, üç bağlam gücü (birinin artık geçersiz — görünür şekilde), eski hız sınırını adlandıran reddedilmiş bir senkron-API kardeşi, personel mühendisinin de dahil olduğu dört tamamlanmış İnceleme zinciri ve kanıt olarak eklenmiş kıyaslama. Teknoloji lideri on dakika okur, hız sınırının değiştiğini görür ve eski düğüme bağlı bir üst öneri açar. Hiç kimse Slack'i kazmaz. Tüm vaat bu: zincirler anlaşmaya ulaşır, ağaç bunu kaydeder — ve kayıt, sorulacağını bilmediğiniz soruları yanıtlar.