راهنمای جامع ایجاد و استفاده از سند ADR در تیم های نرم افزاری

راهنمای جامع ایجاد و استفاده از سند ADR در تیم های نرم افزاری

این محتوا مناسب برنامه نویس های ارشد، مدیران پروژه، Tech Leadها، CTOها و افرادی است که در طراحی و پیاده سازی پروژه ها نقش دارند. 🔞در نتیجه محتوای این بلاگ برای افراد تازه کار مناسب نمی باشد.

این راهنما فرآیند سوابق تصمیم گیری معماری (ADR) را برای پروژه های مهندسی نرم افزار معرفی می کند.  شما با مطالعه ی همین راهنما، می توانید به صورت کامل این اسناد را در تیم خود پیاده سازی کنید تا دستورالعمل های استراتژیک برای پروژه یا محصول تان را مستند کنید و جلوی تصمیم گیری و بحث های مکرر و وقت گیر را در تیم بگیرید.

سند Architectural Decision Records (ADR) چیست؟

در طول توسعه پروژه و محصول، تیم های مهندسی نرم افزار باید برای رسیدن به اهداف خود تصمیمات معماری بگیرند. این تصمیمات می تواند فنی باشد، مانند تصمیم به استفاده از الگوی CQRS، یا  تصمیم به استفاده از گردش کار GitFlow برای مدیریت کد های برنامه. اتخاذ این تصمیم ها فرآیندی زمان بر و دشوار است. تیم ها باید این تصمیم ها را توجیه و مستند کنند و با درجریان قرار دادن ذی نفعان از همسویی همه ی آنها در بخش های مختلف پروژه بهره مند شوند.

وقتی صحبت از تصمیم گیری های معماری است، اغلب موارد سه ضدالگو یا مشکل زیر پدیدار می شود:

  • از ترس انتخاب اشتباه اصلا تصمیمی گرفته نمی شود.
  • تصمیم بدون هیچ توجیهی گرفته می شود و اعضای تیم نمی دانند که چرا این تصمیم گرفته شده است. به همین دلیل یک موضوع چندین بار مورد بحث قرار گیرد.
  • تصمیم های گرفته شده  در یک جا ثبت نمی شود، بنابراین اعضای تیم فراموش می کنند یا نمی دانند که تصمیم گرفته شده است.

این ضد الگوها به ویژه در طول فرآیند توسعه یک محصول یا پروژه مهم هستند.

وقتی از ADR برای مستند سازی تصمیم های گرفته شده و ملاحظاتی که منجر به آن تصمیم شده است استفاده می کنید، افراد مرتبط به آن پروژه که امروز در آن فعالیت می کنند یا در آینده قرار است به آن اضافه شوند با تصمیم های گرفته شده و فرآیند فکری پشت آن آشنا می شوند. همین کار زمان توسعه نرم افزار را کاهش می دهد و مستندات بهتری را برای اعضای فعلی و آینده ی پروژه فراهم می کند.

ADR ها سه نتیجه تجاری را هدف قرار می دهند:

  • آنها اعضای تیم فعلی و آینده را همسو می کنند.
  • آنها یک جهت استراتژیک برای پروژه یا محصول تعیین می کنند.
  • آنها با تعریف فرآیندی برای مستندسازی و انتقال صحیح تصمیمات معماری، از ضد الگوهای تصمیم گیری اجتناب می کنند.

یک دیگر از نتایج مثبت ADR ها این است که به تیم های دیگر اجازه می دهد تا از ملاحظات مطرح شده توسط سایر تیم های توسعه پروژه و محصول بیاموزند و در مورد آنها بینش کسب کنند.


اعضای پروژه سرفصل های هر ADR را مرور می کنند تا  هم یک دید کلی از زمینه پروژه داشته باشند و هم عمیقاً در پیاده سازی پروژه و انتخاب های طراحی غوطه ور شوند.

بعد از اینکه تیم ADR را می پذیرد، دیگر امکان تغییر آن وجود ندارد. اگر بینش جدید نیاز به تصمیم متفاوتی داشته باشد، تیم یک ADR جدید را پیشنهاد می کند. هنگامی که تیم ADR جدید را می پذیرد، جایگزین ADR قبلی می شود.

دامنه فرآیند سند ADR

اعضای پروژه باید برای هر تصمیم مهم معماری که بر پروژه نرم افزار یا محصول تأثیر می گذارد، یک ADR ایجاد کنند، از جمله موارد زیر:

  • ساختار (Structure). مثال: الگوهایی مانند میکروسرویس ها
  • الزامات غیر عملکردی (Non-functional requirements). مثال:  امنیت، در دسترس بودن بالا و تحمل خطا
  • وابستگی ها (Dependencies). مثال: وابستگی اجزا (Component) به هم
  • رابط ها (Interfaces). مثال: API ها و قراردادهای منتشر شده
  • تکنیک های ساخت و ساز(Construction techniques). مثال: کتابخانه ها، چارچوب ها، ابزارها و فرآیندها

الزامات عملکردی و غیرعملکردی رایج‌ترین ورودی‌های فرآیند ADR هستند.

محتویات سند ADR

هنگامی که تیم نیاز به ADR را شناسایی می کند، یکی از اعضای تیم شروع به نوشتن ADR بر اساس یک الگوی پروژه می کند.  این الگو ایجاد ADR را ساده می کند و تضمین می کند که ADR تمام اطلاعات مربوطه را دریافت می کند. حداقل، هر ADR باید زمینه تصمیم، خود تصمیم و پیامدهای تصمیم را برای پروژه و محصولات قابل تحویل آن تعریف کند. 

یکی از  اصلی ترین دلایلی انتخاب ADR، این است که به جای بیان چگونگی پیاده سازی یک تصمیم بر دلیل رسیدن به آن تصمیم تمرکز می کند. با این کار تیم درک می کند چرا یک تصمیم گرفته شده است. در نتیجه خود تیم از لغو آن تصمیم در آینده، توسط دیگرانی که در روز تصمیم گیری نبوده اند جلوگیری می کنند.


فرآیند ایجاد و پذیرش سند ADR

هر عضو تیم می تواند یک ADR ایجاد کند، اما تیم باید تعریفی از مالکیت برای ADR ایجاد کند. هر نویسنده ای که صاحب یک ADR است باید به طور فعال از محتوای ADR محافظت کند.  سایر اعضای تیم همیشه می توانند به ADR کمک کنند. اگر قبل از اینکه تیم، ADR را بپذیرد محتوای یک ADR تغییر کند، مالک باید این تغییرات را تأیید کند.

نمودار زیر فرآیند ایجاد، مالکیت و پذیرش ADR را نشان می دهد.


پس از اینکه تیم به جایی رسید که نیاز داشت درباره ی معماری تصمیمی بگیرد  و مالک آن را شناسایی کرد،  سند ADR توسط مالک و  در حالت پیشنهادی ایجاد می شود. ADRها در حالت پیشنهادی آماده بررسی هستند.

سپس مالک ADR، فرآیند بررسی ADR را آغاز می کند. هدف فرآیند بررسی ADR این است که تیم به این نتیجه برسد که آیا ADR را می پذیرد یا می خواهد آن را رد کند. به عبارت ساده تر در این بخش تیم با مشارکت هم به این تصمیم جمعی میرسند که آیا لازم است روی این موضوع فعالیت کنند یا خیر. در بعضی از موارد ممکن است تیم به این نتیجه برسد که لازم است کارهای بیشتری برای تصمیم گیری درباره ی رد یا پذیرفتن سند انجام شود.

جلسه ی بررسی سند ADR با حضور مالک سند و اعضای تیمی تصمیم گیری برگزار می شود. این جلسه ابتدا یک زمان 10 الی 15 دقیقه ای دارد که هر کسی سند را بخواند و جاهایی که برایش سوال یا ابهامی وجود دارد علامت گذاری کند. بعد از این باید اعضا درباره ی هر کدام از این سوالات و ابهام ها بحث کنند تا به نتیجه برسند.

اگر تیم به این نتیجه برسد که برای بهبود ADR نیاز است کارهایی انجام شود، وضعیت ADR، پیشنهادی باقی می‌ماند. مالک ADR اقدامات را فرموله می‌کند، و با همکاری تیم، یک نفر را مأمور انجام آن کار می کند. هر یک از اعضای تیم می‌توانند در این زمینه مشارکت کنند و کارهای موجود برای بهبود سند را انجام بدهند. این مسئولیت مالک ADR است که روند بازبینی را مجدداً برنامه ریزی کند.

تیم همچنین می تواند تصمیم به رد ADR بگیرد. در این مورد، مالک ADR، دلیلی برای رد اضافه می کند تا از بحث های بعدی در مورد همان موضوع جلوگیری کند. مالک وضعیت ADR را به رد شده (Rejected) تغییر می دهد.

اگر تیم ADR را تأیید کند، به سند تاریخ، نسخه و فهرست افرادی که در آن تصمیم نقش داشته اند را اضافه می‌کند. سپس مالک وضعیت سند را به  تایید شده (Accepted) تغییر می دهد.


سند ADR در بازبینی تغییرات برنامه چه نقشی دارد؟

حالا در صورتی که تغییری در بخشی از برنامه ایجاد شده باشد، سند ADR به کمک تیم می آید تا آن تغییر را اعتبارسنجی کنند. در صورتی که آن تغییر سند ADR را نقض کند، لازم است آن تغییر رد بشود و در غیر این صورت تغییر پذیرفته شود. در نمودار زیر، روند اعتبارسنجی یک تغییر با استفاده از سند ADR را مشاهده می کنید:


به عنوان یک روش خوب (Best Practice) لازم است هر تغییری که روی برنامه اتفاق می افتد، حداقل توسط یکی از اعضای تیم بازبینی شود و مورد تایید قرار بگیرد. ممکن است کسی که درحال بازبینی کد است تغییراتی را پیدا کند که یک یا چند ADR را نقض می‌کند. در این مورد، بازبینی کننده از نویسنده تغییر کد می خواهد که کد را به روز کند و در کامنت های کد به ADR نقش شده اشاره می کند. هنگامی که نویسنده کد را به روز می کند، توسط اعضای تیم دوباره بازبینی و تایید می شود و در پایه کد اصلی ادغام می شود.


فرآیند بازبینی ADR

تیم باید ADR ها را به عنوان اسناد تغییرناپذیر پس از پذیرش یا رد تیم، در نظر بگیرد. تغییرات در یک ADR موجود مستلزم ایجاد یک ADR جدید، ایجاد یک فرآیند بررسی برای ADR جدید و تأیید ADR است. اگر تیم ADR جدید را تأیید کند، مالک باید وضعیت ADR قدیمی را به جایگزین شده (Superseded ) تغییر دهد. نمودار زیر روند به روز رسانی را نشان می دهد.

همانطور که در نمودار زیر هم مشاهده می کنید، تنها یک مرحله نسبت به روند ایجاد سند ADR اضافه شده است، که طی آن سند قبلی تغییر وضعیت می دهد.


بهترین شیوه ها (Best Practices)

مالکیت اسناد را به افراد مختلف بسپارید. هر یک از اعضای تیم باید قدرت ایجاد و داشتن یک ADR را داشته باشد. با این روش کار تحقیقاتی معماری را بین اعضای تیم توزیع می کنید، همچنین حس مالکیت را در فرآیند تصمیم گیری تقویت می کند. با این کار تصمیمات سریعتر گرفته می شود احساس خوب مشارکت در تصمیم گیری ها را خواهند داشت  به جای اینکه آنها را به عنوان تصمیماتی که از سطوح بالاتر سازمان تحمیل شده اند تلقی کند.

تاریخچه ADR را حفظ کنید. ADR ها باید تاریخچه تغییر داشته باشند و هر تغییر باید یک مالک داشته باشد. هنگامی که مالک ADR، آنرا به روز می کند، باید وضعیت ADR قدیمی را به جایگزین شده تغییر دهد، تغییرات خود را در تاریخچه تغییرات ADR جدید یادداشت کند و ADR قدیمی را در گزارش تصمیم گیری نگه دارد.

جلسات بررسی منظم را برنامه ریزی کنید. اگر در یک پروژه جدید  هستید، فرآیند ADR می تواند در ابتدا بسیار شدید باشد. توصیه می‌کنیم قبل یا بعد از جلسه استندآپ روزانه، جلسات منظمی برای بحث درباره ی موضوعات مرتبط با ADR و مرور جلسات قبلی برگزار کنید. با این رویکرد، ADR های تعریف شده در دو یا سه اسپرینت تثبیت می شوند و شما می توانید با جلسات کمتر پایه محکمی بسازید.

ADR ها را در یک مکان مرکزی ذخیره کنید. هر عضو پروژه باید به مجموعه ADR ها دسترسی داشته باشد. توصیه می کنیم ADR ها را در یک مکان مرکزی ذخیره کنید. دو گزینه محبوب برای ذخیره سازی ADR وجود دارد:

  • یک مخزن Git که نسخه ADR ها را آسان تر می کند.
  • یک صفحه ویکی که ADR ها را برای همه اعضای تیم در دسترس قرار می دهد.

مشکل کد ناسازگار را حل کنید. فرآیند ADR مشکل کدهای قدیمی ناسازگار را حل نمی کند. اگر کد قدیمی ای دارید که از ADR‌های تعیین‌شده پشتیبانی نمی‌کند، می‌توانید همزمان با ایجاد تغییرات جدید، کد یا بقیه ی چیزهای مرتبط به کد قدیمی را به‌تدریج به‌روزرسانی کنید، یا تیم شما می‌تواند با ایجاد تسک های بدهی فنی، وقت مشخصی را برای اصلاح کدهای قدیمی صرف کند.


مزایای ایجاد یک فرآیند ADR چیست؟

تیم پروژه باید یک فرآیند ADR ایجاد کند تا تصمیم‌گیری معماری را ساده‌تر کند، از بحث‌های مکرر در مورد موضوعات معماری  جلوگیری کند، و تصمیمات معماری را به طور موثر به همه ی اعضای فعلی و آینده ی تیم منتقل کند.

چه زمانی تیم باید یک ADR ایجاد کند؟

تیم باید یک ADR برای هر جنبه ای از نرم افزار  که بر ساختار (الگوهایی مانند میکروسرویس ها)، الزامات غیرعملکردی (امنیت، در دسترس بودن بالا و تحمل خطا)، وابستگی ها (ارتباط و وابستگی اجزای برنامه به هم)، رابط ها (API ها و  قراردادهای منتشر شده)  و تکنیک های ساخت و ساز (کتابخانه ها، چارچوب ها، ابزارها و فرآیندها) تاثیر میگذارد، ایجاد کند.

تیم هر چند وقت یک بار باید یک ADR را بازبینی کند؟

تیم پروژه باید ADR را حداقل یک بار قبل از پذیرش آن بازبینی کند.

چه کسی باید ADR را ایجاد کند؟

هر عضو تیم می تواند یک ADR ایجاد کند. توصیه می کنیم مفهوم مالکیت را برای ADR ها بین اعضای تیم توزیع کنید. اعضای تیم همیشه می توانند به ADR کمک کنند. مالک ADR باید تغییرات یک ADR را تأیید کند.

ADR باید شامل چه اطلاعاتی باشد؟

حداقل، هر ADR باید زمینه تصمیم، خود تصمیم و پیامدهای تصمیم را برای پروژه و محصولات قابل تحویل آن تعریف کند. زمینه باید راه حل های احتمالی را که تیم در نظر گرفته است ذکر کند. همچنین باید حاوی هر گونه اطلاعات مربوط به پروژه، مشتری یا پشته فناوری باشد. این تصمیم باید  راه حلی را که تیم تصمیم گرفته است، به وضوح بیان کند. از به کار بردن کلماتی مانند "باید" ، "ما استفاده می کنیم..." یا "تیم باید استفاده کند..." خودداری کنید. هر ADR باید یک وضعیت و یک تغییرات ثبت داشته باشد که حاوی تاریخ تغییر و شخصی است که مسئول تغییر است.

از کجا می توانم الگوهای ADR را پیدا کنم؟

در انتهای همین مقاله یک نمونه از این سند آمده است و همچنین  برای مجموعه ای عمومی از الگوهای ADR که معمولاً استفاده می شود، به مخزن ADR GitHub مراجعه کنید


توصیه می‌کنیم از کوچک شروع کنید و مزایای ADR را برای تیم خود ببینید. اگر روی یک پروژه کار می کنید که مراحل اولیه خود را سپری کرده است و در مرحله ی Production قرار دارد، تغییر معماری بعدی را شناسایی کنید و فرآیند ADR پیشنهادی را برای ایجاد اولین ADR خود اعمال کنید.

نقطه شروع دیگر این است که فرآیند کلی توسعه نرم افزار خود را با استفاده از ADR ها مستند کنید. اغلب، فرآیند توسعه مبتنی بر دانش ضمنی است که تیم در هیچ سندی ثبت نکرده است. مستندسازی این فرآیند تجربه روان تری را برای اعضای جدید تیم امکان پذیر می کند.

اگر در یک پروژه مشغول هستید که در ابتدای مسیر توسعه است، فرآیند ADR را اعمال کنید و تمام تصمیمات را از ابتدا در چند جمله ثبت کنید. سپس می توانید به آن ADR ها مراجعه کنید و آنها را با اطلاعات جدید تکمیل کنید. پس از ایجاد ADR های خود، می توانید از آنها به عنوان مرجع در فرآیند بررسی کد خود استفاده کنید.


نمونه سند ADR

عنوان

این تصمیم رویکرد چرخه عمر توسعه نرم افزار را برای توسعه برنامه ABC تعریف می کند.

وضعیت

پذیرفته شده

تاریخ

11-03-2022

متن نوشته

ما باید یک فرآیند توسعه داشته باشیم که ما را قادر به داشتن مسیری برای ویژگی های جدید، رفع فوری ایرادها و انتشار محصول نهایی کند.

تصمیم

ما از یک نسخه اقتباس شده از گردش کار GitFlow برای توسعه برنامه ABC استفاده می کنیم.

برای سادگی، از شاخه های hotfix/* و release/* استفاده نخواهیم کرد، زیرا برنامه ABC به جای استقرار در یک محیط خاص، بسته بندی می شود. به همین دلیل، نیازی به پیچیدگی اضافی نیست که ممکن است ما را از واکنش سریع برای رفع اشکالات در نسخه های نهایی (Production) یا آزمایش نسخه ها در یک محیط جداگانه باز دارد.

استراتژی شاخه بندی توافق شده به صورت زیر است:

  • هر مخزن باید یک شاخه اصلی محافظت شده داشته باشد که برای برچسب گذاری نسخه ها استفاده می شود.
  • هر مخزن باید یک شاخه توسعه محافظت شده برای تمام کارهای توسعه در حال انجام داشته باشد.

عواقب

مثبت:

فرآیند اقتباس شده GitFlow ما را قادر می سازد تا نسخه انتشار برنامه ABC را کنترل کنیم.

منفی:

GitFlow پیچیده تر از توسعه مبتنی بر trunk یا جریان GitHub است و سربار بیشتری دارد.

انطباق

شاخه های main و develop در هر مخزن باید به عنوان Protected علامت گذاری شوند.

تغییرات در شاخه هایmain  و develop  باید با استفاده از merge requests منتشر شود.

برای هر merge requests حداقل یک تأیید لازم است.

یادداشت

نویسنده: جین دو

نسخه: 0.1

تغییرات:

  • 0.1: نسخه پیشنهادی اولیه

منابع:

https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records

https://adr.github.io/

Richards, Mark and Neal Ford. 2020. Fundamentals of Software Architecture. Sebastopol: O'Reilly Media.

از بهترین نوشته‌های کاربران سکان آکادمی در سکان پلاس


online-support-icon