Merge Request (MR): ما هو، وكيفية إنشائه وعملية المراجعة

ما هو Merge Request (MR)؟

Merge Request (MR) — طلب دمج التغييرات من فرع Git إلى آخر، والذي يبدأ عملية مراجعة الكود والفحوصات الآلية. على عكس الدمج المباشر عبر وحدة التحكم، ينشئ MR إجراءً رسميًا: يصف المطور التغييرات، ويعين المراجعين، ويطلق CI/CD، ويتلقى ملاحظات قبل تطبيق التغييرات. هذا عنصر رئيسي في GitLab، لكن الآلية المماثلة في GitHub تُسمى Pull Request (PR).

وفقًا لـ GitLab Documentation, 2026، يتم إنشاء أكثر من 80 مليون Merge Request في GitLab سنويًا. يحتوي كل MR على أربعة مكونات رئيسية: وصف مع سياق التغييرات وقائمة بالـ commits والفرق في الكود (diff) والنقاش (سلسلة النقاش). بدون أحد هذه العناصر، يعتبر MR غير مكتمل.

Merge Request (MR) يحل ثلاث مهام: يمنع التغييرات المباشرة في الفروع المحمية (main, develop)، ويوفر مراقبة الجودة من خلال المراجعة، ويحفظ تاريخ النقاش للمطورين المستقبليين. في GitLab، يتم عرض حالة MR في الواجهة بمؤشرات لونية: رمادي لـ Draft، برتقالي للانتظار، أخضر لـ Approved، أرجواني لـ Merged، وأحمر لـ Closed.

المصطلحات: MR وPR وCR

في منصات Git المختلفة، يُسمى Merge Request بأسماء مختلفة. يستخدم GitLab «Merge Request» (MR)، ويستخدم GitHub «Pull Request» (PR). القياس هو Change Request (CR) في Gerrit. تشير الثلاثة إلى نفس العملية: طلب دمج التغييرات من خلال مراجعة الكود. يعتمد اختيار المصطلح فقط على المنصة المستخدمة في المشروع.

# إنشاء فرع بالتغييرات
git checkout -b feature/add-auth
git commit -m "Add OAuth2 authentication flow"
git push origin feature/add-auth

# يمكنك إنشاء MR عبر واجهة GitLab/GitHub أو CLI:
gh pr create --title "Add OAuth2 authentication flow" \
  --body "Implements OAuth2 with Google and Apple providers" \
  --reviewer "team-lead"

MR مقابل PR: الفرق بين GitLab وGitHub

Merge Request في GitLab وPull Request في GitHub هما آليتان متطابقتان وظيفيًا بأسماء مختلفة. يرجع الاختلاف إلى التاريخ: وضع GitLab نفسه في البداية كبديل مستضاف ذاتيًا لـ GitHub واختار مصطلح «merge request» لعملية الدمج. GitHub، الذي أُطلق سابقًا، استخدم «pull request» — طلب «سحب» (pull) التغييرات إلى الفرع الرئيسي.

وفقًا لـ GitHub Docs, 2024، تدعم كلتا الأداتين نفس مجموعة الميزات: وصف Markdown، وتعيين المراجعين، والتعليق على أسطر محددة من الكود، وحالات الفحص، والدمج التلقائي عند استيفاء الشروط. تتعلق الاختلافات بالواجهة والإمكانيات الإضافية.

كيفية إنشاء Merge Request: دليل خطوة بخطوة

يبدأ إنشاء Merge Request (MR) بنشر فرع بالتغييرات في المستودع البعيد. بعد الدفع (push) إلى GitLab أو GitHub، تظهر في الواجهة زر «Create Merge Request» أو «Compare & Pull Request». يملأ المطور الوصف، ويحدد الفرع الهدف (عادة develop أو main)، ويعين المراجعين، ويُرفق التصنيفات (labels).

وفقًا لـ GitLab Documentation, 2025، يحتوي MR القياسي على عنوان يصل إلى 72 حرفًا ووصفًا مع قالب ورابط للمهمة (issue). يجب أن يجيب الوصف على الأسئلة: ما تم فعله، ولماذا، وكيف تم اختباره. يدعم GitLab الإغلاق التلقائي للمهام عند الدمج باستخدام الكلمات المفتاحية Closes, Fixes, Resolves.

# مثال لقالب .gitlab/merge_request_templates/default.md
## What does this MR do?

[وصف مختصر للتغييرات: ماذا ولماذا]

## How to test

1. تشغيل ./gradlew test
2. التحقق من LoginActivity باستخدام رمز اختبار
3. التأكد من عدم وجود انحدار في AuthManager

## Related issues

Closes #142

دورة حياة MR: من Draft إلى Merged

Merge Request (MR) يمر بخمس حالات في GitLab. الأولى هي Draft (مسودة)، تُوسم بالبادئة «Draft:» في العنوان، وتمنع الدمج. عندما يصبح جاهزًا، يزيل المطور Draft، وينتقل MR إلى حالة Opened — تبدأ مراجعة الكود ويبدأ خط أنابيب CI/CD.

وفقًا لـ GitLab Docs, 2024، في حالة Opened، يراجع المراجعون الـ diff، ويتركون تعليقات، ويطلبون تغييرات من خلال Resolve Threads. عندما تُحل جميع السلاسل ويمر CI/CD بنجاح، يضع المطور المسؤول Approve. بعد ذلك، يمكن دمج MR باستخدام زر Merge، أو انتظار الدمج التلقائي (Auto-merge).

GitLab يدعم ثلاثة خيارات للحالة النهائية: Merged (تم الدمج بنجاح)، وClosed (مغلق دون دمج، مثلاً عند التخلي عن ميزة)، وReopened (إعادة فتح بعد الإغلاق). يتم تسجيل كل حالة في الجدول الزمني لنشاط MR للمراجعة.

الحالات التلقائية والمحفزات

يقوم GitLab تلقائيًا بتحديث حالة Merge Request عند وقوع الأحداث: دفع commits جديدة يعيد تعيين الموافقات، وعند نجاح خط أنابيب CI تصبح الحالة Pipeline passed، وعند الفشل — Pipeline failed (يُمنع الدمج). يمكن تكوين Auto-merge: يتم دمج MR تلقائيًا بعد نجاح CI والحصول على جميع الموافقات المطلوبة.

• Draft — مسودة، يعمل CI لكن الدمج محظور
• Opened — جاهز للمراجعة، تم تعيين المراجعين، خط الأنابيب نشط
• Approved — تم استلام العدد المطلوب من الموافقات
• Merged — تم دمج التغييرات في الفرع الهدف
• Closed — مغلق دون دمج

قواعد مراجعة الكود في Merge Request

مراجعة الكود في Merge Request (MR) هي مرحلة إلزامية في معظم المشاريع التجارية. وفقًا لبحث SmartBear, 2023، تقلل مراجعة الكود مع MR من عدد العيوب بنسبة 30–60% وتسرع من تأهيل المطورين الجدد. القاعدة الأساسية هي أن يتم فحص كل MR بواسطة مطور واحد على الأقل، ويفضل اثنان لم يشاركوا في كتابة الكود.

فحص MR يشمل خمسة معايير: صحة المنطق، والامتثال لنمط الكود، وتغطية الاختبارات، والأمان، والأداء. في GitLab، يمكن تكوين الموافقات المطلوبة (Required Approvals) — العدد الإلزامي من الموافقات قبل الدمج، مثلاً موافقتان لـ main وواحدة لـ develop.

النقاش في MR يتم في سلاسل (Threads) — تعليقات على أسطر محددة من الكود. يجب حل كل سلسلة قبل الدمج. لتسريع المراجعات، يُنصح بتحديد حجم MR: 200–400 سطر من التغييرات. وفقًا لـ Google Research (2022)، يتم مراجعة MR الأكبر من 400 سطر بكفاءة أقل بنسبة 30%.

خط أنابيب CI/CD في Merge Request

عند إنشاء Merge Request (MR)، يبدأ خط أنابيب CI/CD تلقائيًا. في GitLab، يحدث هذا من خلال ملف .gitlab-ci.yml، وفي GitHub من خلال سير عمل GitHub Actions. يشمل خط الأنابيب بناء المشروع، والاختبارات الوحدوية، والـ linters، والتحليل الثابت (SAST)، وفحص تغطية الكود.

وفقًا لـ GitLab Blog, 2024، تظهر حالة خط الأنابيب مباشرة في MR: علامة خضراء (passed)، وصليب أحمر (failed)، أو دائرة صفراء (running). إذا فشل خط الأنابيب، يحظر GitLab زر Merge حتى يتم الإصلاح. في الإعدادات، يمكن تفعيل «Merge when pipeline succeeds» — الدمج التلقائي بعد نجاح خط الأنابيب.

# .gitlab-ci.yml — مثال لمشروع Android
test:
  stage: test
  script:
    - ./gradlew ktlintCheck
    - ./gradlew testDebugUnitTest
  only:
    - merge_requests

build:
  stage: build
  script:
    - ./gradlew assembleDebug
  only:
    - merge_requests

طرق الدمج: Squash وMerge Commit وFast-Forward

GitLab وGitHub يقدمان ثلاث طرق دمج لـ Merge Request. يعتمد الاختيار على سياسة الفريق ونظافة التاريخ المطلوبة. Merge Commit ينشئ commit دمج منفصلًا، محتفظًا بكل تاريخ فرع الميزة. Squash يدمج كل commits الفرع في commit واحد على الفرع الهدف. Fast-Forward يطبق commits خطيًا بدون commit دمج.

وفقًا لـ GitLab Docs, 2025، يُفضل Squash للمشاريع ذات الكثافة العالية من commits (20+ commit في فرع ميزة واحد). Fast-Forward إلزامي لتطوير Trunk-Based Development. يُستخدم Merge Commit في Git Flow للحفاظ على دلالات التفرع.

• Merge Commit — يحافظ على التاريخ، ينشئ commit دمج، مناسب لـ Git Flow
• Squash — يدمج كل commits في واحد، تاريخ نظيف، يفقد commits الوسيطة
• Fast-Forward — تاريخ خطي بدون commit دمج، إلزامي في TBD

أفضل الممارسات: كيفية كتابة MR جيد

Merge Request (MR) عالي الجودة يقلل وقت المراجعة وعدد الأخطاء. القاعدة الأولى هي أن MR واحد يحل مهمة واحدة. إذا كانت التغييرات تؤثر على عدة ميزات غير مرتبطة، فيجب تقسيمها إلى MR منفصلة. ثانيًا، يجب أن يكون عنوان MR غنيًا بالمعلومات: «Add OAuth2 authentication with Google provider» بدلاً من «Fix stuff» أو «Update code».

وفقًا لـ Google Engineering Practices, 2024، يحتوي MR الجيد على وصف للسياق: لماذا التغييرات ضرورية، وكيف تم اختبارها، وما المخاطر الموجودة. يجب ألا يتجاوز حجم MR 400 سطر من التغييرات. إذا كان الحجم أكبر، فيجب تفكيك المهمة إلى مهام فرعية. بالنسبة للوثائق والاختبارات، الاستثناءات مقبولة ولكن مع شرح.

Merge Request (MR) يجب أن يتضمن اختبارات آلية للوظائف الجديدة. في GitLab، يمكن تكوين سياسة Coverage Check — يتم حظر MR تلقائيًا إذا انخفضت تغطية الكود عن حد معين (مثلاً 80%). يضمن ذلك أن الوظائف الجديدة لا تقلل من الجودة العامة للمشروع.

• MR واحد — مهمة واحدة: قسّم التغييرات الكبيرة إلى عدة MR صغيرة
• وصف مع قالب: استخدم .gitlab/merge_request_templates للتوحيد
• حجم يصل إلى 400 سطر: MR الكبيرة تُراجع بشكل أبطأ وبأخطاء أكثر
• الاختبارات إلزامية: يجب تغطية الميزات الجديدة باختبارات وحدوية

قوالب وصف MR

يدعم GitLab قوالب Merge Request من خلال ملفات .gitlab/merge_request_templates/. يشمل القالب أقسامًا: ما تم فعله، وكيفية الاختبار، والمهام ذات الصلة، وقائمة التحقق. استخدام القوالب يُسرع إنشاء MR ويضمن أن المطورين لا ينسون تضمين معلومات مهمة. في وصف MR، يجب تحديد المهام ذات الصلة (Closes #N) للإغلاق التلقائي للمهام عند الدمج.