استاندارد مهندسی توسعه نرم‌افزار، مدیریت کد و انتشار خودکار در اکوسیستم متن‌باز هلدینگ زنجیره تأمین بهشت و متارنگ (MetaRang)

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

این استاندارد مهندسی توسط مهندس امین دهقان نژاد (شناسه شهروندی: HM-2000007)، مسئول مدیریت گیت‌هاب زیرساخت‌های مرتبط با زنجیره تأمین بهشت در سازمان رسمی GitHub.com/iranpsc، بر پایه بهترین تجارب جهانی (Industry Best Practices)، استاندارد Conventional Commits 1.0.0 و پروتکل Semantic Versioning 2.0.0 طراحی، پیاده‌سازی و ابلاغ شده است.

هدف از استقرار این پروتکل، کاهش خطاهای انسانی در فرآیند انتشار، تضمین کیفیت کد پیش از ادغام (Shift-Left QA) و ایجاد زنجیره‌ای کاملاً خودکار، شفاف و قابل ردیابی از زمان نگارش کد تا انتشار نسخه رسمی در GitHub Releases است.

۱. قوانین شاخه‌ها و ایزولاسیون کد (Branching & Isolation Rules)

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

توسعه مستقیم و ارسال کامیت (Direct Push) بر روی شاخه‌های اصلی main و dev به‌صورت سیستمی مسدود شده و اکیداً ممنوع است. تمامی تغییرات باید در شاخه‌های مستقل و ایزوله انجام شوند.

هر تسک، قابلیت جدید، رفع باگ یا بازآرایی کد باید در یک Branch مستقل ایجاد شود که منشعب از آخرین وضعیت شاخه dev باشد. این رویکرد امکان توسعه هم‌زمان، مدیریت بهتر تغییرات و جلوگیری از تداخل میان فعالیت‌های توسعه‌دهندگان را فراهم می‌کند.

تمامی Pull Requestهای مربوط به توسعه روزمره باید منحصراً به مقصد شاخه dev ارسال شوند. انتقال تغییرات به شاخه main تنها در چارچوب چرخه انتشار رسمی و پس از بررسی و تأیید نهایی مجاز خواهد بود.

گردش کار استاندارد ایجاد شاخه در محیط CLI

ابتدا توسعه‌دهنده باید شاخه dev را دریافت و با آخرین تغییرات مخزن همگام‌سازی کند. سپس شاخه مستقلی متناسب با نوع تسک ایجاد نماید.

نمونه دستورات استاندارد:

git checkout dev
git pull origin dev
git checkout -b feat/auth-user-authentication

برای رفع باگ، نام شاخه می‌تواند به شکل زیر باشد:

git checkout -b fix/payment-callback-validation

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

git checkout -b refactor/database-query-optimization

نام‌گذاری شاخه‌ها باید شفاف، معنادار و متناسب با نوع تغییر باشد تا امکان شناسایی سریع هدف توسعه فراهم شود.

۲. قوانین ثبت کامیت‌ها (Conventional Commits Specification)

تمامی کامیت‌های ثبت‌شده توسط توسعه‌دهندگان باید از استاندارد جهانی Conventional Commits پیروی کنند. این استاندارد امکان تحلیل خودکار تاریخچه کد توسط موتورهای CI/CD، تولید یادداشت‌های انتشار و مدیریت دقیق نسخه‌های نرم‌افزار را فراهم می‌سازد.

ساختار استاندارد پیام کامیت به شکل زیر است:

<type>(<optional-scope>): <description>

در این ساختار، type نوع تغییر، scope محدوده یا بخش مرتبط با تغییر و description شرح مختصر و دقیق آن را مشخص می‌کند.

انواع استاندارد کامیت‌ها

feat — قابلیت جدید (New Feature):

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

نمونه:

feat(auth): add user authentication

fix — رفع باگ (Bug Fix):

برای اصلاح خطاها یا رفتارهای نادرست در کدهای موجود استفاده می‌شود. این نوع تغییر معمولاً موجب افزایش نسخه جزئی (PATCH) خواهد شد.

نمونه:

fix(wallet): resolve rounding error in PSC token transfer

perf — بهبود عملکرد (Performance):

برای ثبت تغییراتی به کار می‌رود که با هدف افزایش سرعت اجرا، بهینه‌سازی پردازش یا کاهش مصرف منابع انجام شده‌اند. این نوع کامیت موجب افزایش نسخه PATCH می‌شود.

نمونه:

perf(query): optimize spatial polygon indexing for map loader

refactor — بازآرایی کد (Refactoring):

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

نمونه:

refactor(admin): simplify sidebar permission middleware

docs — مستندات (Documentation):

برای ایجاد یا به‌روزرسانی مستندات، راهنماها و توضیحات فنی استفاده می‌شود. این نوع کامیت به‌تنهایی موجب افزایش نسخه نرم‌افزار نخواهد شد.

test — تست‌های خودکار (Automated Tests):

برای افزودن یا اصلاح تست‌های واحد (Unit Tests)، تست‌های یکپارچه‌سازی (Integration Tests) و تست‌های انتهابه‌انتها (E2E) به کار می‌رود. این تغییرات به‌تنهایی موجب افزایش نسخه نخواهند شد.

chore — امور نگهداری (Maintenance):

برای تغییرات مربوط به ابزارهای بیلد، وابستگی‌های نرم‌افزاری، پکیج‌ها و تنظیمات زیرساختی استفاده می‌شود. این نوع کامیت نیز به‌تنهایی موجب افزایش نسخه نخواهد شد.

رعایت دقیق این ساختار برای تمامی توسعه‌دهندگان الزامی است؛ زیرا موتور انتشار خودکار بر اساس نوع و محتوای کامیت‌ها، تصمیم‌گیری می‌کند.

۳. قوانین ارسال و مستندسازی Pull Request

تمامی Pull Requestهای ثبت‌شده در مخازن سازمان باید به‌عنوان اسناد مهندسی کامل و قابل بررسی تهیه شوند. رعایت الزامات زیر پیش از ادغام تغییرات الزامی است.

استاندارد عنوان Pull Request

عنوان هر Pull Request باید دقیقاً مطابق استاندارد Conventional Commits نوشته شود. گیت کنترلی خودکار تعریف‌شده در فایل pr-linter.yml از ادغام Pull Requestهایی که عنوان غیراستاندارد دارند جلوگیری می‌کند.

نمونه عنوان‌های معتبر:

feat(auth): add user authentication
fix(api): handle null pointer in citizen profile endpoint
refactor(ci): update instant-release workflow for semantic release

در مقابل، عنوان‌هایی مانند موارد زیر غیراستاندارد محسوب شده و توسط گیت کنترلی مسدود خواهند شد:

Update readme.md
Refactor instant-release workflow
fixed bug

جامعیت توضیحات در بدنه Pull Request

توسعه‌دهنده موظف است تمامی تغییرات انجام‌شده را به‌صورت دقیق، شفاف و کامل در بخش توضیحات Pull Request ثبت کند.

صرفاً نوشتن توضیح برای آخرین کامیت، به‌هیچ‌عنوان کافی نیست و چنین Pull Requestی ممکن است توسط بازرسان کد رد شود.

مستندسازی باید به‌صورت تجمعی و از زمان آخرین Pull Request ادغام‌شده در شاخه مقصد انجام گیرد. به این معنا که تمامی تغییرات انجام‌شده در این بازه، شامل قابلیت‌های جدید (Features)، اصلاحات و رفع باگ‌ها (Fixes)، بهبودهای عملکردی (Improvements) و تغییرات فنی و زیرساختی، باید در توضیحات Pull Request منعکس شوند.

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

اجرای الزامی تست‌ها پیش از ارسال

پیش از ارسال Pull Request، توسعه‌دهنده موظف است تمامی تست‌های مرتبط، شامل Unit Tests، Integration Tests و بررسی‌های Linter را در محیط توسعه اجرا کند و از صحت نتایج آن‌ها اطمینان حاصل نماید.

ارسال تغییرات بدون بررسی کیفیت کد و اجرای تست‌های مرتبط، مغایر با استاندارد مهندسی سازمان است.

استاندارد ادغام Pull Request

در تنظیمات مخازن سازمان، قابلیت ادغام Pull Requestها بر اساس الگوی Allow squash merging تنظیم شده است.

عنوان پیش‌فرض کامیت حاصل از ادغام نیز بر اساس عنوان Pull Request تعیین می‌شود. این سیاست با هدف حفظ تاریخچه‌ای تمیز، استاندارد و قابل تحلیل در شاخه‌های اصلی اجرا می‌شود.

۴. قوانین انتشار نسخه خودکار (Semantic Release Rules)

فرآیند انتشار نسخه در تمامی مخازن سازمان به‌صورت خودکار و مبتنی بر معماری Semantic Release اجرا می‌شود.

نقطه آغاز انتشار خودکار

انتشار نسخه رسمی از طریق پایپ‌لاین Semantic Release و بلافاصله پس از ادغام تغییرات تأییدشده در شاخه main آغاز می‌شود.

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

تحلیل تجمعی کامیت‌های قابل انتشار

هنگام انتشار نسخه جدید، تمامی کامیت‌های قابل انتشار از آخرین Release رسمی تا زمان انتشار جدید به‌صورت یکجا بررسی و تحلیل می‌شوند.

بنابراین، یادداشت‌های انتشار (Release Notes) باید شامل مجموع تمامی تغییرات قابل انتشار در این بازه زمانی باشند، نه صرفاً تغییرات آخرین Pull Request.

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

مسئولیت توسعه‌دهندگان در فرآیند انتشار

مسئولیت ثبت دقیق، شفاف و کامل تغییرات بر عهده تمامی توسعه‌دهندگان است.

هیچ تغییری نباید بدون توضیحات مناسب و استاندارد وارد چرخه انتشار شود. کیفیت مستندات کامیت‌ها و Pull Requestها مستقیماً بر صحت و جامعیت یادداشت‌های انتشار خودکار تأثیر می‌گذارد.

ماتریس افزایش نسخه در Semantic Versioning

بر اساس پروتکل Semantic Versioning 2.0.0، شماره نسخه نرم‌افزار از سه بخش اصلی تشکیل می‌شود:

MAJOR.MINOR.PATCH

هر بخش متناسب با نوع تغییرات قابل انتشار افزایش می‌یابد.

تغییرات از نوع fix، perf و refactor موجب افزایش نسخه جزئی (PATCH) می‌شوند. برای مثال، نسخه v1.0.0 پس از چنین تغییراتی به v1.0.1 ارتقا پیدا می‌کند.

تغییرات از نوع feat موجب افزایش نسخه فرعی (MINOR) می‌شوند. برای مثال، نسخه v1.0.1 به v1.1.0 ارتقا خواهد یافت.

در صورت وجود تغییرات ناسازگار با نسخه‌های قبلی (Breaking Changes)، نسخه اصلی (MAJOR) افزایش پیدا می‌کند. برای مثال، نسخه v1.1.0 به v2.0.0 تغییر خواهد کرد.

تغییرات ناسازگار باید با علامت ! در عنوان کامیت یا با درج عبارت BREAKING CHANGE: در بدنه کامیت مشخص شوند تا موتور انتشار بتواند افزایش نسخه اصلی را تشخیص دهد.

۵. مراجع فنی و زیرساخت‌های اجرایی

به‌منظور ایجاد شفافیت و امکان بررسی مستقیم سازوکارهای کنترلی و انتشار خودکار، دو Workflow اصلی در مخزن مرجع سازمان معرفی شده‌اند.

PR Gatekeeper: این Workflow مسئول اعتبارسنجی عنوان Pull Requestها و جلوگیری از ادغام درخواست‌های مغایر با استانداردهای تعریف‌شده است.

نشانی مرجع:

https://github.com/iranpsc/Metaverse-Rang-Microservice-Admin-Panel/blob/main/.github/workflows/pr-linter.yml

Instant Release: این Workflow مسئول اجرای فرآیند انتشار خودکار نسخه‌ها پس از ادغام تغییرات در شاخه main است.

نشانی مرجع:

https://github.com/iranpsc/Metaverse-Rang-Microservice-Admin-Panel/blob/main/.github/workflows/instant-release.yml

این دو زیرساخت در کنار استانداردهای شاخه‌بندی، کامیت و مستندسازی Pull Request، زنجیره کنترل کیفیت و انتشار نرم‌افزار را در مخازن سازمان تکمیل می‌کنند.

جمع‌بندی

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

اجرای دقیق قوانین شاخه‌بندی و ایزولاسیون کد، ثبت کامیت‌های استاندارد، مستندسازی جامع Pull Requestها، اجرای تست‌های پیش از ادغام و استفاده از Semantic Release، موجب کاهش خطاهای انسانی، افزایش کیفیت نرم‌افزار و حفظ پایداری زیرساخت‌های عملیاتی خواهد شد.

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