قرارداد نامگذاری شاخهها
این سند، استاندارد نامگذاری Branchها در تمامی پروژههای شرکت را تعریف میکند. رعایت این استاندارد برای تمامی اعضای تیم توسعه الزامی است و با هدف ایجاد یک رویه یکپارچه در مدیریت تغییرات، بازبینی فنی و رهگیری فعالیتهای توسعه تدوین شده است.
استفاده از یک الگوی نامگذاری واحد، ارتباط میان JIRA Issue، Branch، Merge Request (MR) و Release را شفاف کرده و فرآیندهای توسعه، گزارشگیری و ممیزی (Audit) را سادهتر میکند.
اهداف
این استاندارد با اهداف زیر تعریف شده است:
- ایجاد ساختاری یکپارچه برای نامگذاری Branchها
- افزایش خوانایی و قابلیت تشخیص Branchها
- حذف نامهای مبهم یا سلیقهای
- تسهیل رهگیری تغییرات در چرخه توسعه نرمافزار
- ایجاد ارتباط مستقیم میان JIRA Issue، Branch، Merge Request و نسخههای منتشرشده
با توجه به مدیریت همزمان چندین پروژه مستقل در شرکت، نام هر Branch باید همواره به صورت مستقیم به JIRA Issue مربوطه اشاره کند.
فلسفه نامگذاری Branchها
در این استاندارد، نام Branch صرفاً به عنوان یک شناسه (Identifier) در نظر گرفته میشود، نه محلی برای توصیف تغییرات.
توضیحات مربوط به هدف تغییر، جزئیات پیادهسازی و اطلاعات فنی در بخشهای زیر ثبت میشوند:
- JIRA Issue
- Commit Message
- Merge Request
در نتیجه، افزودن اطلاعاتی مانند نوع تغییر (feat یا fix)، نام توسعهدهنده یا توضیح مختصر تغییر در نام Branch، علاوه بر ایجاد افزونگی، احتمال ناهماهنگی میان منابع مختلف را نیز افزایش میدهد.
به همین دلیل، نام هر Branch باید صرفاً از JIRA Issue Key تشکیل شده باشد تا ارتباط میان کد، مستندات و فرآیندهای توسعه همواره شفاف، یکتا و قابل رهگیری باقی بماند.
ساختار استاندارد
فرمت نامگذاری Branchها به صورت زیر است:
<JIRA-ISSUE-KEY>
JIRA Issue Key
نام Branch باید دقیقاً برابر با JIRA Issue Key باشد و هیچ بخش دیگری به آن اضافه نشود.
ZIRSAKHT-241
OMRAN-87
SAMPAD-1024
HAMYAR-19
قوانین نامگذاری
در نامگذاری Branchها رعایت موارد زیر الزامی است:
- نام Branch باید دقیقاً مطابق JIRA Issue Key باشد.
- JIRA Issue Key باید همواره با حروف بزرگ (UPPERCASE) نوشته شود.
- از افزودن هرگونه Prefix یا Suffix خودداری شود.
- استفاده از نوع تغییر (مانند
feat،fixیاhotfix) در نام Branch مجاز نیست. - از درج نام توسعهدهنده، شناسه شخصی، Scope یا توضیح مختصر تغییر در نام Branch استفاده نشود.
- نام Branch باید از قالب تعریفشده پروژه در JIRA پیروی کند.
ZIRSAKHT-241
OMRAN-87
SAMPAD-1024
HAMYAR-19
ZIRSAKHT-55
OMRAN-27
feat/ZIRSAKHT-241/add-webhook-handler
fix/OMRAN-87/refresh-token-expiry
hotfix/SAMPAD-1024/fix-timeout
mehdi_branch
update-code
final-version
fix-final-final
ZIRSAKHT241
zirsakht-241
ZIRSAKHT-241-fix
الزامات
ارتباط مستقیم با JIRA
با مشاهده نام Branch باید بدون نیاز به بررسی Commitها یا Merge Request، بتوان JIRA Issue متناظر را شناسایی کرد.
اطلاعات مربوط به نوع تغییر، جزئیات پیادهسازی و توضیحات فنی باید در JIRA Issue، Commitها و Merge Request ثبت شوند، نه در نام Branch.
هر Branch فقط به یک JIRA Issue اختصاص دارد
هر Branch باید صرفاً برای پیادهسازی یک JIRA Issue ایجاد شود و تنها یک Merge Request از آن ایجاد گردد.
OMRAN-121-123
OMRAN-121-SAMPAD-122
OMRAN-121
SAMPAD-122
ترکیب چند JIRA Issue در یک Branch مجاز نیست.
استفاده از نامهای توصیفی مجاز نیست
نام Branch نباید بر اساس توضیح تغییر انتخاب شود.
login-fix
OMRAN-87
مرجع اصلی توضیح تغییرات، JIRA Issue است و نام Branch صرفاً نقش شناسه آن را ایفا میکند.
طول نام Branch
نام Branch نباید شامل هیچ بخش اضافهای باشد و تنها از JIRA Issue Key تشکیل میشود.
در نتیجه، طول نام Branch به صورت طبیعی تابع ساختار JIRA Issue Key همان پروژه خواهد بود.
جمعبندی
رعایت این استاندارد باعث میشود:
- ارتباط میان Branch و JIRA کاملاً شفاف و بدون ابهام باشد.
- فرآیندهای Technical Review و Merge با سرعت و دقت بیشتری انجام شوند.
- رهگیری تغییرات در پروژههای متعدد سادهتر شود.
- گزارشگیری، ممیزی (Audit) و مدیریت انتشار نسخهها با دقت بیشتری انجام گیرد.
هر Branch باید تنها از JIRA Issue Key تشکیل شده باشد. وجود هرگونه اطلاعات اضافی در نام Branch، به منزله عدم رعایت استاندارد نامگذاری خواهد بود.