Pull Request: ما هو، عملية الإنشاء ومراجعة الكود

ما هو Pull Request؟

Pull Request (PR) هو طلب رسمي لتضمين تغييرات من فرع إلى آخر ضمن نظام تحكم بالنسخ موزع. PR هو عنصر أساسي في التطوير التعاوني على منصات GitHub وGitLab وBitbucket، حيث يجمع بين مناقشة الكود والاختبارات الآلية وعملية الموافقة على التغييرات.

الاسم «Pull Request» يعكس جوهر العملية: يطلب المطور (request) من مالك المستودع «سحب» (pull) تغييراته. تم تقديم المصطلح بواسطة GitHub في عام 2008 — قبل ذلك، كانت آلية مماثلة موجودة في شكل تصحيحات وmerge requests (مصطلح GitLab). اليوم، PR هو المعيار الفعلي لتطوير الفرق باستخدام Git.

وفقاً لـ GitHub Octoverse, 2025، 89% من المشاريع مفتوحة المصدر تتطلب إنشاء PR لإجراء التغييرات. في التطوير المؤسسي، تصل هذه النسبة إلى 95%. أصبح PR ليس مجرد أداة تقنية، بل جزءاً من ثقافة التطوير: من خلال PR يتم نقل المعرفة واكتشاف الأخطاء ومواءمة القرارات المعمارية.

مكونات Pull Request

PR النموذجي يتكون من عنوان ووصف وقائمة الملفات المعدلة (diff) وتعليقات المقيّمين وحالات فحوصات CI. كل PR مرتبط بفرع مصدر وفرع هدف محددين، وبعد الدمج يمكن حذفه تلقائياً.

كيفية إنشاء Pull Request

إنشاء PR يبدأ بنشر فرع الميزة في المستودع البعيد. بعد الرفع، يفتح المطور PR عبر واجهة المنصة أو عبر CLI (gh, glab). دعنا نستعرض العملية باستخدام GitHub كمثال.

رفع الفرع وفتح PR

الخطوة الأولى هي رفع فرع الميزة إلى المستودع البعيد وإنشاء Pull Request عبر الواجهة web أو سطر الأوامر.

# إنشاء ورفع فرع الميزة
git checkout -b feature/biometric-auth
git add src/auth/
git commit -m "feat: add biometric authentication"
git push -u origin feature/biometric-auth

# إنشاء PR عبر GitHub CLI
gh pr create --title "feat: add biometric authentication" \
  --body "Implements fingerprint and face recognition login.
  Closes #142" \
  --base develop

بعد إنشاء PR، GitHub يقوم تلقائياً بتشغيل خطوط CI (GitHub Actions)، ويتحقق من وجود تعارضات مع الفرع الهدف، ويدعو المقيّمين. يمكن تكوين قالب وصف PR عبر .github/PULL_REQUEST_TEMPLATE.md بحيث تحتوي جميع PR على الأقسام المطلوبة: الهدف، التغييرات، الاختبارات، المهام ذات الصلة.

الوصف والوسم

وصف PR الجيد يتضمن: رابط للمهمة (issue/ticket)، وصفاً موجزاً للتغييرات، تعليمات الاختبار، وقائمة بالتغييرات ذات الصلة. تساعد labels (bug, feature, refactoring) في تصنيف PR، بينما يتم تعيين assignees وreviewers تلقائياً عبر CODEOWNERS.

# تعيين المقيّمين عبر CODEOWNERS (ملف في جذر المستودع)
# مثال .github/CODEOWNERS:
# src/auth/ @team-auth @senior-dev
# src/api/ @team-backend
# *.kt @kotlin-team

# إنشاء PR مع تعيين المقيّمين عبر gh cli
gh pr create --reviewer "team-auth" --label "feature"

CODEOWNERS هي آلية قياسية في GitHub/GitLab لتعيين المقيّمين تلقائياً بناءً على الملفات المعدلة. على سبيل المثال، أي تغييرات في دليل src/auth/ تعين تلقائياً team-auth وsenior-dev كمقيّمين. هذا يسرع العملية ويضمن أن الأشخاص المناسبين يرون PR.

تحديث PR بناءً على المراجعات

بعد تلقي تعليقات المقيّم، يقوم المطور بإجراء التصحيحات في نفس فرع الميزة ويرفع commits جديدة — يتم تحديث PR تلقائياً. من المهم عدم إعادة كتابة التاريخ (rebase) في فرع ميزة منشور إذا كان PR مفتوحاً بالفعل، لأن هذا يكسر الروابط إلى commits محددة في التعليقات.

# إجراء تغييرات بناءً على تعليقات المقيّم
git checkout feature/biometric-auth
# تصحيح الكود
git commit -m "fix: handle biometric timeout per review"
git push

# سيتم تحديث PR تلقائياً
# بعد الموافقة — دمج PR عبر واجهة GitHub

عملية مراجعة الكود

مراجعة الكود هي عنصر أساسي في Pull Request. يقوم المقيّم بالتحقق من التغييرات من حيث الصحة، أسلوب الكود، الأمان، والاتساق المعماري. المراجعة الجيدة لا تمنع الأخطاء فحسب، بل تنشر المعرفة حول قاعدة الكود داخل الفريق.

Engineering Practices من Google (2025) توصي بمبادئ مراجعة الكود التالية: يجب أن يفهم المقيّم سياق التغييرات، ويقدم توصيات محددة بدلاً من الملاحظات العامة، ويفصل التعليقات الفنية والأسلوبية. يجب ألا يتجاوز وقت المراجعة 24 ساعة من لحظة إنشاء PR.

لتطوير التطبيقات المحمولة، تتضمن مراجعة الكود فحوصات محددة: التوافق مع targetSdk، المعالجة الصحيحة لدورة الحياة (Android) / دورة حياة view (iOS)، عدم وجود تسرب للذاكرة (LeakCanary, Instruments)، دعم الوضع المظلم والتوطين. يمكن أتمتة هذه الفحوصات عبر linters وDetekt/ktlint.

أنواع التعليقات

منصات PR تدعم ثلاثة أنواع من التعليقات: عامة (على PR بأكمله)، سطرية (على سطر معين من الكود)، واقتراحات (مع كود بديل). الاقتراحات تسمح بتطبيق التغيير بنقرة واحدة، مما يسرع العملية ويقلل عدد التكرارات.

بعد حل جميع التعليقات واجتياز فحوصات CI، يرسل المقيّم موافقة (Approved). يمكن دمج PR. GitHub وGitLab يدعمان قواعد حماية الفروع: عدد الموافقات المطلوب، فحوصات CI إلزامية، وحظر الرفع إلى main دون PR. لمشاريع التطبيقات المحمولة، تتضمن حماية الفروع أيضاً التحقق من البناء: لا يمكن دمج PR إذا لم يتم بناء التطبيق (gradle build failed / xcodebuild failed).

حل التعارضات في PR

تعارضات الدمج في Pull Request هي حالة شائعة في العمل الجماعي النشط. توفر المنصات حل التعارضات عبر الواجهة web (للتعارضات البسيطة) أو توصي بحلها محلياً. GitHub Actions تتحقق تلقائياً من قابلية الدمج مع كل رفع إلى فرع الميزة وتضع علامة على PR كمتضارب إذا كان الدمج غير ممكن.

أفضل ممارسات Pull Request

Pull Requests الفعالة تسرع مراجعة الكود وتقلل عدد الأخطاء. أظهرت دراسة SmartBear (2025) أن PR التي يصل حجمها إلى 200 سطر من الكود تتلقى ضعف عدد التعليقات المفيدة مقارنة بـ PR التي يزيد حجمها عن 1000 سطر، وينخفض وقت المراجعة 3 مرات.

• PR صغيرة — الحجم الأمثل 100-300 سطر. قسّم PR الكبيرة إلى أجزاء منطقية: كل PR يحل مهمة واحدة. هذا يبسط المراجعة ويقلل احتمال التعارضات
• وصف واضح — عنوان حسب Conventional Commits (feat:, fix:, refactor:)، الجسم يحتوي على «ماذا ولماذا» بدلاً من «كيف» (الكود يتحدث عن نفسه). النموذج: الهدف → التغييرات → الاختبارات → المشكلات ذات الصلة
• ردود سريعة — المراجعة خلال 24 ساعة. إذا انتظر PR أكثر من يوم، يفقد الفريق السياق ويزداد عدد تعارضات الدمج
• الأتمتة — يجب تشغيل linters وأدوات التنسيق والاختبارات تلقائياً عند إنشاء PR. لا تسمح بدمج PR مع فحوصات CI حمراء
• Draft PR — استخدمه للمناقشة المبكرة للهندسة المعمارية. Draft PR لا يتطلب مراجعة ولا يمكن دمجه، لكنه يسمح بعرض الكود على الزملاء في مرحلة مبكرة

ممارسات إضافية: لا تنشئ PR مساء الجمعة (لن يراجعها أحد حتى الاثنين)، اطلب المراجعة من 1-2 شخص (أكثر يبطئ العملية دون تحسين الجودة)، استخدم squash merge لضغط التاريخ قبل الدمج. لمشاريع التطبيقات المحمولة، يوصى أيضاً بإضافة رابط لبناء الاختبار (Firebase App Distribution / TestFlight) في وصف PR ليتمكن المقيّم من التحقق من التغييرات في التطبيق العامل.

Pull Request على منصات مختلفة

المنصات الرئيسية للعمل مع Pull Requests هي GitHub وGitLab وBitbucket. على الرغم من المفهوم المشترك، لكل منها ميزات تستحق النظر عند اختيار أداة للفريق.

GitHub هي المنصة الأكثر شعبية مع أكبر مجتمع، وActions لـ CI/CD، ونظام بيئي واسع من التطبيقات (GitHub Marketplace). GitLab تتميز بـ CI/CD المدمج وإمكانية النشر الذاتي الكامل. Bitbucket متكامل بشكل وثيق مع Jira ونظام Atlassian، وشائع في البيئات المؤسسية.

لتطوير التطبيقات المحمولة، غالباً ما يتم تحديد اختيار المنصة من خلال قدرات CI/CD: GitHub Actions تدعم runners من macOS لبناء iOS، GitLab لديها runners مدمجة لـ iOS/Android، Bitbucket يتكامل جيداً مع Firebase Test Lab. بغض النظر عن المنصة، تبقى عملية PR كما هي: فرع → مراجعة → CI → دمج.