راهنمای نحوه‌ی توسعه، برنچ‌بندی و مستندسازی

هدف این سند

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

هر نیروی جدیدی که به تیم اضافه می‌شود، باید همین یک سند را بخواند تا دقیقاً بداند باید چطور کار را شروع و تمام کند.

اصل پایه: هیچ کدی بدون تیکت جیرا وجود ندارد

هر تغییری در کد — چه یک فیچر جدید، چه یک باگ‌فیکس، چه حتی یک رفکتور کوچک — باید پیش از شروع یک تیکت متناظر در جیرا داشته باشد. کلیدواژه‌ی پروژه PEP است، پس هر تیکت با شناسه‌ای مثل PEP-123 شناخته می‌شود.

قانون ساده است:

اگر تیکت جیرا وجود ندارد، برنچ هم وجود ندارد.

اگر کاری هست که باید انجام شود ولی تیکتی برایش ثبت نشده، اول باید تیکت ساخته شود، بعد کار شروع شود — نه برعکس.

ساختار نام‌گذاری برنچ

هر برنچ باید مستقیماً به شماره‌ی تیکت جیرا ارجاع بدهد. الگوی پیشنهادی:

<نوع>/PEP-<شماره>-<توضیح-کوتاه-انگلیسی>

مثال‌ها:

feature/PEP-123-survey-nps-scoring
fix/PEP-145-customer-console-sql-injection
refactor/PEP-160-bi-sync-batch-processing

نکات:

• شماره‌ی تیکت (PEP-123) همیشه باید عیناً در نام برنچ باشد؛ این همان چیزی است که در آینده امکان جست‌وجو و ردگیری تاریخچه را می‌دهد.
• توضیح کوتاه فقط برای خوانایی است، نه برای جایگزینیِ تیکت.
• نوع برنچ (feature / fix / refactor / hotfix) باید با نوع تیکت در جیرا همخوانی داشته باشد.

فرآیند کار، از شروع تا پایان

1. تیکت را در جیرا پیدا یا ایجاد کن. مطمئن شو شرح تیکت واضح است — چه مشکلی حل می‌شود، چرا.
2. برنچ را بر اساس شماره‌ی همان تیکت بساز — طبق الگوی بالا.
3. کار را روی همان برنچ انجام بده. کدی که به یک تیکت مشخص مرتبط نیست، جای دیگری غیر از این برنچ ندارد.
4. درخواست مرج (Merge Request) بزن. عنوان MR باید با شماره‌ی تیکت شروع شود (مثلاً PEP-123: افزودن امتیازدهی NPS به سوروی).
5. بررسی و تست. کیفیت کد و رفتار آن توسط تسترِ تیم بررسی می‌شود؛ تا زمانی که تأیید نگیرد مرج نمی‌شود.
6. مرج فقط وقتی انجام می‌شود که:
   • برنچ به یک تیکت معتبر و موجود در جیرا وصل باشد؛
   • تیکت وضعیت آماده برای مرج را داشته باشد؛
   • تست/بررسی انجام و تأیید شده باشد.

اگر یکی از این سه شرط برقرار نباشد، MR رد می‌شود — فارغ از اینکه کد چقدر خوب نوشته شده باشد. این تنها راهی است که این قانون واقعاً اجرا می‌شود، نه فقط روی کاغذ می‌ماند.

چرا این ساختار مهم است

• ردگیری تاریخچه: با جست‌وجوی شماره‌ی تیکت می‌توانیم مستقیماً به دلیل، بحث‌ها و تصمیم‌های پشت هر تکه کد برسیم.
• مستندسازی محصول: همین سیستم داکیومنتی که داریم می‌سازیم، به این وابسته است که بدانیم هر تغییر ماژول از کجا آمده. بدون تیکت مشخص، پر کردن بخش‌هایی مثل «چرا این تغییر انجام شد» یا «به چه درخواستی نیاز داشت» در فرم مستندسازی ماژول‌ها هم عملاً غیرممکن می‌شود.
• کنترل ورودی کد به سیستم: این پروژه سال‌هاست در حال توسعه است بدون این نظم؛ از این نقطه به بعد، هر خط کدی که وارد می‌شود باید بتواند به یک منبع مشخص در جیرا اشاره کند.

خلاصه برای اعضای جدید تیم

اگر تازه به این پروژه ملحق شده‌ای، فقط این چند خط را به‌خاطر بسپار:

1. بدون تیکت PEP در جیرا شروع نکن.
2. اسم برنچ را با PEP-<شماره> بساز.
3. عنوان MR را با شماره‌ی تیکت شروع کن.
4. تا تأیید تستر، مرج نمی‌شود.
5. اگر تیکتی برای کاری که می‌خواهی انجام بدهی وجود ندارد، اول تیکت بساز.