Mimari karar kayıtları nasıl tutulur?
Mimari karar kaydı neyi kapsar?
Architectural Decision Record (ADR), mimari açıdan önemli tek bir kararı ve gerekçesini kaydeder. GitHub adr organizasyonu, mimari kararı, mimari açıdan önemli bir işlevsel veya işlevsel olmayan gereksinimi karşılayan gerekçeli bir tasarım seçimi olarak tanımlar. Bir projede oluşturulan ve sürdürülen ADR koleksiyonu ise decision log olarak adlandırılır.
AWS Prescriptive Guidance’a göre bir ADR, ekibin oluşturmayı planladığı yazılım mimarisinin önemli bir yönü hakkında yaptığı seçimi açıklar. Kayıt, kararın kendisini, bağlamını ve sonuçlarını içerir. Kayıtların durumları vardır ve her kayıt bir yaşam döngüsünden geçer.
Microsoft Azure Well-Architected Framework, sistemin yapısını veya temel kalite özelliklerini etkileyen ya da geri alınması zor olan seçimlerin kayda alınmasını söyler. Kayda alınan kararların yanında, elenen alternatifler de yer alır. Kararın etkileri anlatılırken gereksinimler ve kısıtlar da kayda girer.
AWS, mimari açıdan önemli kararların kapsamına yapıyı, işlevsel olmayan gereksinimleri, bağımlılıkları, arayüzleri ve oluşturma tekniklerini dahil eder. Güvenlik, yüksek erişilebilirlik ve hata toleransı işlevsel olmayan gereksinimlere verdiği örneklerdir. Bileşenler arasındaki coupling bağımlılıklara; API’ler ve yayımlanmış sözleşmeler ise arayüzlere örnektir. Kitaplıklar, framework’ler, araçlar ve süreçler de oluşturma teknikleri başlığına girer.
AWS’ye göre işlevsel ve işlevsel olmayan gereksinimler, ADR sürecinin yaygın girdileridir. Bir ekip ADR ihtiyacını belirlediğinde, ekip üyelerinden biri proje genelinde kullanılan bir şablonla kaydı yazmaya başlar. Şablon, kayıt oluşturmayı kolaylaştırır ve ilgili bilgilerin kayda alınmasını sağlar.
AWS, decision log’un proje bağlamının yanı sıra uygulama ve tasarım hakkında ayrıntılı bilgiler sunduğunu belirtir. Proje üyeleri, bağlama genel bir bakış edinmek için ADR başlıklarını gözden geçirir. Uygulama ve tasarım seçimlerini daha ayrıntılı anlamak için kayıtların içeriğini okurlar.
Bir kaydın içeriği
AWS, her ADR’de en azından kararın bağlamının, kararın kendisinin ve kararın proje ile teslim edilecek çıktılar üzerindeki sonuçlarının tanımlanmasını ister. ADR yapısı, ekibin kararı nasıl uyguladığından çok neden aldığına odaklanır.
Microsoft Azure, kayıtların aynı yapıyı izlemesi için bir şablon tasarlanmasını önerir. Önerdiği ortak alanlar arasında bağlamı içeren problem tanımı, değerlendirilen seçenekler ve kararın sonucu bulunur. Önemli trade-off’lar, karara duyulan güven düzeyi ve kayıt durumu da bu yapının parçalarıdır.
Martin Fowler’a göre gerekçe, kararı gerekli kılan problemi ve hesaba katılan trade-off’ları özetlemelidir. Ciddi biçimde değerlendirilen alternatifler, artıları ve eksileriyle açıkça listelenebilir. Sonuçlar bazen gerekçeden anlaşılır; bazen de ayrı bir bölümde açıkça belirtilir.
Fowler, kararların belli bir belirsizlik altında alındığını ve güven düzeyinin kaydedilebileceğini belirtir. Aynı bölümde, ekibin kararı yeniden değerlendirmesini gerektirecek ürün bağlamı değişiklikleri de belirtilebilir. Microsoft Azure da düşük güven düzeyiyle alınan mimari açıdan önemli bir kararın bu durumunun kaydedilmesinin, ilerideki yeniden değerlendirmelerde yararlı olabileceğini söyler.
Microsoft Azure, kararların sonuçlarının gizlenmemesi gerektiğini belirtir. Bağlam ve gerekçe de her kayıtta yer almalıdır. Gerekçe bulunmadığında, koşullar değiştiğinde paydaşların kararın hâlâ geçerli olup olmadığını değerlendirmesi zorlaşır.
Bir karar kısa, orta ve uzun vadeli yaklaşımlar gibi birden fazla aşamaya yol açacaksa Microsoft Azure, her aşamanın ayrı bir karar kaydı olarak tutulmasını söyler. Aynı yaklaşım, kayıtların kısa, konuya bağlı ve olgusal olmasını ister. ADR bir tasarım rehberine dönüştürülmez; ek gerekçe veya tasarım çalışmasına bağlantı verilebilse de kararın kendisi bu ek materyal olmadan açık olmalıdır.
Fowler, ADR yazımının kararın kaydını oluşturmanın yanında düşünceleri netleştirmeye de hizmet ettiğini anlatır. Grup halinde yazma sürecinde farklı görüşler ortaya çıkabilir ve bu görüşler tartışılabilir. Fowler’ın anlattığı Advice Process içinde ADR hazırlanırken alınan görüşler de kayda dahil edilir. Kayıt kısa tutulacaksa görüşler ADR’de özetlenebilir ve tam kayıt ayrı tutulabilir.
Dosyalar ve durumlar
Fowler, ADR’lerin ilgili kod tabanının source repository’sinde tutulmasının yaygın bir yaklaşım olduğunu yazar. Yaygın konumlardan biri doc/adr dizinidir. Markdown gibi hafif bir markup language kullanılması, kayıtların kod gibi okunmasına ve aralarındaki farkların görülmesine olanak verir. Bir build görevi, kayıtları ürün ekibinin web sitesinde yayımlamak için de kullanılabilir.
Fowler’a göre her kayıt ayrı bir dosya olmalıdır. Dosya adında artan bir sıra numarası ve kararı anlatan bir ad bulunması, dizin listesindeki kayıtların okunmasını kolaylaştırır. En önemli içerik kaydın başında, ayrıntılar ise daha sonra yer alır. Fowler kısa ve doğrudan kayıtlar tutulmasını, destekleyici materyal varsa ona bağlantı verilmesini önerir.
Fowler’ın durum tanımlarında, tartışılan bir kayıt Proposed durumundadır. Ekip kabul ettiğinde ve karar etkin olduğunda durum Accepted olur. Karar önemli ölçüde değiştirildiğinde veya yerini başka bir karar aldığında durum Superseded olur; kayıtta yerini alan ADR’ye bağlantı bulunur.
Microsoft Azure, durum bilgisinin özellikle karar sayısı arttığında her kararın geçerli durumunu açık tuttuğunu belirtir. Azure’un verdiği durum örnekleri Proposed, Accepted ve Superseded’dır. Durum, bağlam ve seçeneklerle birlikte şablonda ortak biçimde yer alabilir.
Microsoft Azure, decision log’un yalnızca ekleme yapılan bir kayıt olarak sürdürülmesini söyler. Kabul edilmiş kayıtlara geri dönülüp içerikleri düzenlenmez. Bir karar değişirse eskisinin yerini alan yeni bir kayıt yazılır ve iki kayıt birbirine bağlanır. Böylece düşüncenin geçmişi ile yönün ne zaman ve neden değiştiği görünür kalır.
Ekip değerlendirmesi nasıl ilerler?
AWS’nin sürecinde her ekip üyesi ADR oluşturabilir. Ekip, her ADR için sahipliğin ne anlama geldiğini belirler. Kayıt sahibi içeriği etkin biçimde sürdürür ve iletir; diğer ekip üyeleri de kayda katkıda bulunabilir. Kayıt kabul edilmeden önce içeriği değişirse bu değişiklikleri sahibi onaylar.
Ekip mimari kararı ve sahibini belirledikten sonra, sahip ADR’yi Proposed durumunda sunar. Bu durumdaki kayıt değerlendirmeye hazırdır. Sahip değerlendirme sürecini başlatır; sürecin amacı ekibin ADR’yi kabul edip etmeyeceğine, yeniden çalışma gerekip gerekmediğine veya kaydın reddedilip reddedilmeyeceğine karar vermesidir.
AWS’ye göre proje ekibi, kayıt sahibi dahil olmak üzere ADR’yi değerlendirir. Toplantı, kaydı okumaya ayrılmış bir zaman dilimiyle başlar. Ekip üyeleri bu sırada açık olmayan konuları işaretlemek için yorum ve sorular ekler. Ardından kayıt sahibi her yorumu okur ve ekiple tartışır.
Ekip kaydı iyileştirmek için yapılacak işler belirlerse ADR Proposed durumunda kalır. Kayıt sahibi işleri tanımlar ve ekiple birlikte her işe bir sorumlu atar. Ekip üyeleri bu işlere katkıda bulunabilir ve onları çözebilir. Değerlendirmenin yeniden planlanması kayıt sahibinin sorumluluğudur.
Ekip ADR’yi reddederse sahip, aynı konuda gelecekte tekrar tartışma yaşanmaması için ret gerekçesini ekler ve durumu Rejected olarak değiştirir. Ekip ADR’yi onaylarsa sahip paydaş listesini ekler ve durumu Accepted yapar.
AWS, ekibin ADR’leri mümkün olduğunda kod ve mimari değerlendirmelerinde başvuru olarak kullanmasını söyler. Bir kod değerlendirmesinde değişikliğin bir veya daha fazla ADR’ye aykırı olduğu görülürse değerlendirici, değişikliğin yazarından kodu güncellemesini ister ve ilgili ADR’nin bağlantısını paylaşır.
Kayıt değiştiğinde ve yaklaşımın sınırları
AWS, kabul edilen veya reddedilen ADR’lerin değişmez kabul edilmesini ister. Mevcut bir kararı değiştirmek için yeni bir ADR oluşturulur; yeni kayıt değerlendirilir ve onaylanır. Yeni ADR onaylandığında eski kaydın sahibi, eski kaydın durumunu Superseded olarak değiştirir.
Fowler, ADR’leri ürün repository’sinde tutmanın tek bir kod tabanından daha geniş bir ekosistemi kapsayan kararlar için işe yaramayacağını belirtir. Ayrıca bazı kişiler, kayıtların git içinde tutulmasının geliştirici olmayanların bunlarla çalışmasını fazla zorlaştırdığını düşünür.
Microsoft Azure’a göre ADR bir iş yükünün başlangıcında başlatılır ve iş yükünün yaşamı boyunca sürdürülür. Mevcut bir iş yükü için de ADR başlatılır; geçmiş kararlara ilişkin veriler varsa kayıtlar bilinen kararlar temelinde geriye dönük oluşturulur. Karar kaydı, ilk tasarımın ötesinde, gelecekteki işlevsel ve işlevsel olmayan gereksinimlere ilişkin tasarım yönlerini de kapsar.