طلبات السحب

طلب السحب (pull request، PR)، ويُسمّى أيضاً merge request على GitLab، هو طلب دمج: «هذا عملي على فرع، أرجو مراجعته ثم دمجه في main». هو نقطة اللقاء بين الشفرة والفريق.

طلب السحب ليس مجرد زر «دمج». هو فضاء نقاش حول الشفرة: تعليقات، اقتراحات، اختبارات آلية، موافقة. هنا تُحسَم الجودة.

قبل فتح طلب سحب، يجب دفع فرعك إلى GitHub.

الخطوة 1 — دفع الفرع :

git switch feature/recherche
git push -u origin feature/recherche

الخطوة 2 — فتح طلب السحب (خياران) :

• من واجهة GitHub: يظهر شريط « Compare & pull request »؛ ننقر، ونختار فرع الأساس (main) والفرع المقارَن (feature/recherche).
• من سطر الأوامر بـ GitHub CLI :

# إنشاء طلب السحب دون مغادرة الطرفية
gh pr create --base main --head feature/recherche \
  --title "إضافة البحث" \
  --body "تنفيذ شريط البحث مع مرشحات."

وصف طلب سحب جيد يحتوي :

العنوان والوصف يقرأهما بشر مستعجلون. كن صريحاً: «يصحّح انهيار تسجيل الدخول» أفضل ألف مرة من «fix bug».

تمرين مصغّر — من الفرع الحالي feature/recherche، أنشئ طلب سحب نحو main بـ gh، بعنوان واضح.

gh pr create --base main --head feature/recherche \
  --title "إضافة البحث" --body "تنفيذ شريط البحث."

مراجعة الشفرة (code review) قلب طلب السحب: زميل أو أكثر يقرأون التعديلات، يسألون، يقترحون تحسينات، ثم يوافقون أو يطلبون تغييرات.

الأحكام الثلاثة الممكنة على GitHub :

من جهة المؤلف، بعد التعليقات، نصحّح وندفع من جديد: يتحدّث طلب السحب تلقائياً.

# التصحيح بعد المراجعة
git switch feature/recherche
# ... تعديلات ...
git commit -am "أخذ ملاحظات المراجعة في الحسبان"
git push          # يتحدّث طلب السحب وحده

ما ينظر إليه مراجع جيد :

• هل الشفرة تفعل ما تدّعيه؟ (منطق صحيح)
• هل هي مقروءة وقابلة للصيانة؟
• هل هناك اختبارات؟ هل CI أخضر؟
• هل توجد مشكلات أمن أو أداء؟

مراجعة الشفرة ليست حكماً على الشخص، بل تحسين جماعي للمنتج. ننتقد الشفرة، لا المؤلف. ونبرز أيضاً ما أُحسن عمله.

بعد الموافقة على طلب السحب واخضرار CI، ندمجه. يقترح GitHub ثلاث طرائق، تغيّر شكل السجل.

# الدمج من الطرفية بـ GitHub CLI
gh pr merge 42 --squash --delete-branch

بعد الدمج، ننظّف :

# حذف الفرع البعيد (غالباً تلقائي)
git push origin --delete feature/recherche

# تحديث المحلي
git switch main
git pull origin main

# حذف الفرع المحلي
git branch -d feature/recherche

Squash and merge شائع جداً: ميزة = إيداع نظيف واحد في main. يصبح السجل قائمة مقروءة من الميزات، لا فوضى «wip» و «fix typo» و «oups».

تمرين مصغّر — بـ gh، ادمج طلب السحب رقم 42 بـ squash واحذف الفرع في العملية نفسها. اكتب الأمر.

طلب سحب فعّال هو طلب صغير وواضح ومختبَر. هذه عادات الفرق المتقدّمة.

# ربط قضية تلقائياً في الوصف
gh pr create --title "إضافة تصدير CSV" \
  --body "يسمح بتصدير البيانات بصيغة CSV. Closes #57"

طلب سحب من 1 000 سطر ينال «LGTM» (looks good to me) بلا مراجعة حقيقية — لا أحد يملك شجاعة قراءة الكل. طلب من 50 سطراً ينال ملاحظات ثمينة. الصغير = مراجعة جدية.

تمرين مصغّر — أي كلمة مفتاح تضيفها في وصف طلب سحب لإغلاق القضية #57 تلقائياً عند الدمج؟

السؤال 1: لماذا يُستخدم طلب السحب؟

a) لحذف فرع

b) لطلب مراجعة فرع ودمجه في فرع آخر

c) لتثبيت Git

d) لاستنساخ مستودع

السؤال 2: ماذا يجب فعله قبل فتح طلب سحب على GitHub؟

a) حذف main

b) دفع الفرع نحو المستودع البعيد (git push)

c) إغلاق الطرفية

d) تعطيل CI

السؤال 3: ماذا يعني « Request changes » أثناء مراجعة؟

a) الشفرة موافَق عليها

b) تصحيحات لازمة قبل الدمج

c) حُذف طلب السحب

d) أُنشئ مستودع جديد

السؤال 4: أي طريقة دمج تضغط كل إيداعات الفرع في واحد؟

a) Create a merge commit

b) Squash and merge

c) Rebase and merge

d) Cherry-pick

السؤال 5: لماذا نفضّل طلبات سحب صغيرة؟

a) تستهلك مساحة قرص أقل

b) تُراجَع أسرع وبجدية أكبر

c) GitHub يفرضها

d) تغني عن كتابة اختبارات

المطلوب

أنهيت ميزة على الفرع feature/footer. نفّذ دورة طلب السحب كاملة بـ GitHub CLI (gh) :

1. ادفع الفرع.
2. افتح طلب سحب نحو main بعنوان واضح ورابط قضية (Closes #12).
3. بعد الموافقة، ادمجه بـ squash واحذف الفرع.
4. حدّث مستودعك المحلي.

التصحيح

# 1. دفع الفرع
git switch feature/footer
git push -u origin feature/footer

# 2. فتح طلب السحب
gh pr create --base main --head feature/footer \
  --title "إضافة تذييل الموقع" \
  --body "يضيف تذييلاً متجاوباً مع روابط وإشارات قانونية. Closes #12"

# 3. بعد الموافقة: دمج squash + حذف الفرع
gh pr merge --squash --delete-branch

# 4. تحديث المحلي
git switch main
git pull origin main
git branch -d feature/footer

النتيجة المتوقعة :

$ git log --oneline -1
a1b2c3d Ajout du pied de page du site (#13)

الرقم بين قوسين (#13) يضيفه GitHub تلقائياً: رقم طلب السحب. النقر عليه يعيد إلى كامل نقاش المراجعة. تتبّع تام.

النقاط التي يجب تذكّرها

1. طلب السحب يطلب مراجعة فرع ثم دمجه: هو فضاء نقاش.
2. إنشاء طلب سحب: ادفع الفرع، ثم افتحه من الواجهة أو gh pr create.
3. مراجعة الشفرة تنتهي بـ Approve أو Request changes أو Comment؛ ننتقد الشفرة لا المؤلف.
4. ثلاث طرائق دمج: merge commit، squash and merge، rebase and merge.
5. ممارسات جيدة: طلبات صغيرة، موضوع واحد، CI أخضر، قضية مرتبطة.
6. بعد الدمج: احذف الفرع وحدّث محليك.

ما يلي

تتقن دورة المساهمة على مستودعك. الدرس 04 — سير العمل التعاوني يفتح تعاوناً أوسع: fork، clone، القضايا، وممارسات الفريق الجيدة.