قوانین Merge Request

هر تغییری که قرار است وارد شاخه‌های اصلی پروژه شود، باید از مسیر Merge Request (MR) عبور کند. یعنی ابتدا تغییرات روی branch کاری انجام می‌شود، سپس MR ساخته می‌شود تا تغییرات دیده، بررسی و تایید شوند. commit مستقیم روی branchهای محافظت‌شده مثل main و develop ممنوع است، چون این branchها باید همیشه پایدار، قابل پیگیری و قابل اعتماد بمانند.

به زبان ساده، MR یک مرحله کنترل کیفیت قبل از merge است. این مرحله کمک می‌کند:

• تغییرات قبل از ورود به branch اصلی review شوند
• خطاهای احتمالی زودتر پیدا شوند
• دلیل تغییرات برای اعضای دیگر تیم شفاف باشد
• تاریخچه پروژه منظم و قابل فهم باقی بماند

warning

اگر بدون MR روی branch محافظت‌شده commit مستقیم انجام شود، ممکن است کد بدون review وارد پروژه شود، CI یا فرایند بررسی دور زده شود، و بعداً پیدا کردن علت یک bug یا تصمیم فنی سخت‌تر شود.

MR دقیقاً چیست؟

MR یعنی درخواست رسمی برای وارد شدن تغییرات شما به branch اصلی تیم.

در این راهنمای جامع دُرنیکا، قاعده اصلی این است:

• هر task فقط یک MR دارد
• هر MR فقط برای یک task ساخته می‌شود

به زبان عملی، MR سه کار انجام می‌دهد:

• به بقیه تیم نشان می‌دهد دقیقاً چه چیزی تغییر کرده است
• فرصت review فنی قبل از merge را ایجاد می‌کند
• یک سابقه شفاف از دلیل تغییر، تصمیم‌ها و محدودیت‌ها نگه می‌دارد

MR را می‌توان این‌طور در نظر گرفت:

• branch محل انجام کار شماست
• commitها مراحل انجام کار شما هستند
• MR توضیح رسمی شما به تیم درباره آن کار است

tip

MR صرفاً «درخواست merge» نیست. MR سند اصلی توضیح تغییر برای reviewer، مدیر فنی و اعضای بعدی تیم است.

جریان استاندارد کار

روند عادی کار باید این‌طور باشد:

1. از develop یا branch مبنا، branch کاری خود را با نام issue key بسازید.
2. تغییر را فقط در scope همان task انجام دهید.
3. commitهای خوانا و استاندارد بزنید.
4. قبل از ساخت MR، تغییرات خود را self-review کنید.
5. MR را با توضیح کامل بسازید.
6. بعد از review و approval، MR merge شود.

چه زمانی MR آماده است؟

MR زمانی آماده است که:

• مسئله دقیقاً مشخص باشد
• راه‌حل پیاده‌سازی شده باشد
• تغییرات اضافه، موقت یا بی‌ربط حذف شده باشند
• نویسنده بتواند در چند خط توضیح دهد «مسئله چه بود» و «چه چیزی تغییر کرد»

اگر هنوز نمی‌توانید مسئله و راه‌حل را شفاف توضیح دهید، معمولاً MR هنوز آماده نیست.

warning

اگر یک branch یا یک MR شامل بیش از یک task باشد، باید کار را جدا کنید. در این استاندارد، هر task مسیر مستقل خودش را دارد: یک branch و یک MR.

الزامات قبل از ساخت MR

• branch از مبنای درست ساخته شده باشد
• branch دقیقاً برابر Jira issue key باشد
• branch فقط مربوط به همان task باشد
• commitها از Conventional Commits پیروی کنند
• lintهای مرتبط اجرا شده باشند
• migrationها local بررسی شده باشند
• تغییرات خارج از scope حذف شده باشند

ساختار پیشنهادی Description

هر MR باید حداقل این بخش‌ها را داشته باشد:

• خلاصه مسئله
• توضیح راه‌حل
• تغییرات
• ضمیمه UI در صورت نیاز
• لینک Jira

الگوی پیشنهادی:

## خلاصه مسئله

## راه‌حل

## تغییرات

- Database:
- Permission:
- API:
- UI:

## Jira

محتوای MR

هر MR باید شامل موارد زیر باشد:

• خلاصه مسئله
• توضیح راه‌حل
• تغییرات در database، permission، API یا UI
• screenshot یا video در صورت نیاز
• لینک Jira task یا issue

نوشتن Description

1. خلاصه مسئله

در این بخش باید توضیح دهید مشکل یا نیاز چه بوده است.

نمونه خوب:

• کاربر بعد از refresh token منقضی‌شده، پیام خطای نامشخص دریافت می‌کرد
• در فرم ثبت اطلاعات، فیلد کد ملی بدون validation ذخیره می‌شد
• در لیست فاکتورها، pagination روی داده زیاد باعث کندی شدید شده بود

نمونه ضعیف:

• bug fixed
• changes applied
• updated code

2. توضیح راه‌حل

در این بخش باید بگویید دقیقاً چه تغییری داده‌اید.

نمونه خوب:

• منطق بررسی انقضای refresh token به لایه service منتقل شد و response خطا استاندارد شد
• برای فیلد کد ملی validation سمت server اضافه شد و پیام خطا به translation منتقل شد
• query لیست فاکتورها بازنویسی شد و eager loading غیرضروری حذف شد

نمونه ضعیف:

• fixed it
• optimized code
• refactor done

3. تغییرات

این بخش کمک می‌کند reviewer سریع‌تر ریسک تغییر را بفهمد.

برای مثال، در این بخش می‌توانید به این موارد اشاره کنید:

• آیا migration دارد یا نه
• آیا permission جدید اضافه شده یا نه
• آیا response API تغییر کرده یا نه
• آیا UI یا متن‌های translation تغییر کرده یا نه

نمونه:

• Database: ندارد
• Permission: ندارد
• API: ساختار خطای endpoint ورود اصلاح شده است
• UI: ندارد

4. ضمیمه UI

اگر تغییر شما روی رابط کاربری اثر دارد، می‌توانید screenshot یا video اضافه کنید.

هر زمان reviewer نتواند فقط با خواندن کد، تأثیر تغییر را به‌درستی ارزیابی کند، باید مدرک بصری مثل Screenshot، GIF یا Video اضافه شود.

نمونه:

• تغییر متن placeholder
• تغییر layout فرم
• تغییر ترتیب actionها
• تغییر modal، table یا pagination

tip

برای reviewer مهم است که بدون اجرای پروژه هم بتواند تغییر UI را بفهمد.

سناریوهای رایج

سناریو 1: bugfix ساده

مثال:

• Jira: OMRAN-87
• مسئله: تاریخ انقضای refresh token درست بررسی نمی‌شد
• خروجی MR: فقط اصلاح منطق انقضا و response خطا

اگر مسئله فقط مربوط به refresh token است، MR هم باید فقط همان بخش را اصلاح کند.

برای مثال، در همین MR نباید هم‌زمان:

• ساختار controller را تغییر دهید
• اسم فایل‌ها یا کلاس‌ها را عوض کنید
• بخش دیگری از سیستم را هم cleanup کنید

reviewer باید با دیدن MR سریع متوجه شود که این تغییر فقط برای حل همان bug ساخته شده است.

سناریو 2: تغییر UI

مثال:

• Jira: HAMYAR-19
• مسئله: placeholder فیلد جستجو گمراه‌کننده است
• خروجی MR: فقط تغییر متن، spacing یا ظاهر مرتبط

در این حالت بهتر است screenshot یا video اضافه شود تا reviewer بدون اجرا کردن پروژه هم تغییر را متوجه شود.

سناریو 3: تغییر همراه migration

مثال:

• Jira: ZIRSAKHT-55
• مسئله: نیاز به فیلد جدید برای ذخیره وضعیت تایید
• خروجی MR شامل: migration، validation، ذخیره‌سازی و نمایش مرتبط

در این حالت باید در Description صریح بنویسید:

• migration اضافه شده است
• داده قبلی چه وضعیتی پیدا می‌کند
• آیا rollback نکته خاصی دارد یا نه

warning

اگر MR هم‌زمان bugfix، refactor، rename، cleanup و تغییر UI را با هم دارد، تقریباً همیشه بیش از حد بزرگ است و باید split شود.

نمونه Description

نمونه 1: bugfix

خلاصه مسئله: کاربر در زمان استفاده از refresh token منقضی‌شده، پیام خطای دقیق دریافت نمی‌کرد و تشخیص علت مشکل سخت بود.

راه‌حل: منطق بررسی انقضای token به service منتقل شد و response خطا برای این سناریو استاندارد شد.

تغییرات: -- Database: ندارد -- Permission: ندارد -- API: response خطای endpoint ورود اصلاح شد -- UI: ندارد

جیرا: OMRAN-87

نمونه 2: تغییر UI

خلاصه مسئله: متن placeholder در فرم جستجو برای کاربر واضح نبود و باعث ثبت ورودی اشتباه می‌شد.

راه‌حل: placeholder اصلاح شد و label فیلد با متن دقیق‌تر جایگزین شد.

تغییرات: -- Database: ندارد -- Permission: ندارد -- API: ندارد -- UI: placeholder و label فیلد جستجو تغییر کرده است

جیرا: HAMYAR-19

نمونه 3: validation

خلاصه مسئله: در فرم ثبت اطلاعات، فیلد کد ملی بدون validation مناسب ذخیره می‌شد و ورودی نامعتبر وارد سیستم می‌گردید.

راه‌حل: validation مربوط به کد ملی در request اضافه شد و پیام خطا به translation منتقل شد تا خروجی برای کاربر واضح‌تر باشد.

تغییرات: -- Database: ندارد -- Permission: ندارد -- API: پیام خطای validation این فیلد مشخص‌تر شده است -- UI: ندارد

جیرا: SAMPAD-42

نمونه 4: تغییر همراه migration

خلاصه مسئله: برای ثبت وضعیت تایید، فیلد مجزا در داده‌ها وجود نداشت و وضعیت از روی چند شرط پراکنده تشخیص داده می‌شد.

راه‌حل: فیلد جدید approval_status اضافه شد و منطق ذخیره و نمایش آن در flow مربوطه یکپارچه شد.

تغییرات: -- Database: migration جدید برای اضافه شدن approval_status -- Permission: ندارد -- API: فیلد approval_status به response مربوطه اضافه شده است -- UI: نمایش وضعیت تایید در صفحه جزئیات به‌روز شده است

جیرا: ZIRSAKHT-55

اندازه MR

MR باید تا حد ممکن کوچک و قابل review باشد. اگر تغییر شامل چند concern مستقل است، باید split شود.

قاعده ساده:

• یک task = یک MR
• یک MR = یک task

نمونه اشتباه:

• اصلاح bug لاگین
• refactor service پرداخت
• تغییر UI داشبورد

این سه مورد باید در MRهای جداگانه انجام شوند، مگر اینکه واقعاً یک مسئله واحد باشند.

نمونه درست:

• فقط اصلاح validation یک endpoint
• فقط تغییر متن‌ها و layout یک فرم
• فقط اضافه شدن یک migration و استفاده از همان فیلد در همان flow

tip

اگر reviewer برای فهم MR مجبور شود از شما جلسه بگیرد، Description به اندازه کافی شفاف نیست.

موارد ممنوع

• MR بدون توضیح
• یک MR برای چند task
• ترکیب refactor و feature بدون ضرورت
• تغییرات format گسترده در کنار تغییر behavior
• merge کردن بدون approval لازم
• bypass کردن CI یا review

جمع‌بندی

یک MR خوب باید برای reviewer این چهار سؤال را سریع جواب دهد:

• مسئله چه بوده است؟
• چه چیزی تغییر کرده است؟
• اثر این تغییر کجاست؟
• آیا scope تغییر کنترل‌شده و قابل review است؟

اگر reviewer برای فهم این چهار مورد مجبور شود کد را حدس بزند، Description شما کافی نیست.