Git و GitHub
طلبات السحب (Pull Requests)
طلبات السحب (Pull Requests)
طلبات السحب (PRs) هي واحدة من أقوى ميزات التعاون في GitHub. توفر طريقة منظمة لاقتراح التغييرات، وتسهيل مراجعة الكود، ودمج الكود بأمان في قاعدة الكود الرئيسية.
ما هي طلبات السحب؟
طلب السحب هو طلب لدمج كود من فرع إلى آخر. يُطلق عليه "طلب سحب" لأنك تطلب من مشرف المستودع "سحب" تغييراتك إلى فرعهم.
مفهوم أساسي: طلبات السحب ليست ميزة في Git - إنها ميزة في GitHub تعزز سير عمل Git. منصات أخرى مثل GitLab تسميها "طلبات الدمج".
سير عمل طلب السحب
إليك سير عمل PR النموذجي:
1. إنشاء فرع ميزة من main
2. إجراء التغييرات والالتزام بها
3. دفع الفرع إلى GitHub
4. فتح طلب سحب
5. مراجعة الكود والمناقشة
6. إجراء التغييرات المطلوبة (إن وجدت)
7. الموافقة من المراجعين
8. دمج PR في فرع main
9. حذف فرع الميزة
إنشاء طلب السحب الأول
دعنا ننشئ PR خطوة بخطوة:
# الخطوة 1: إنشاء والتبديل إلى فرع جديد
git checkout -b feature/add-contact-page
# الخطوة 2: إجراء التغييرات
echo "<h1>اتصل بنا</h1>" > contact.html
git add contact.html
git commit -m "Add contact page"
# الخطوة 3: دفع الفرع إلى GitHub
git push -u origin feature/add-contact-page
بعد الدفع، سيعرض GitHub رابطاً لإنشاء طلب سحب. يمكنك أيضاً إنشاء واحد يدوياً:
1. انتقل إلى مستودعك على GitHub
2. انقر على علامة التبويب "Pull requests"
3. انقر على "New pull request"
4. حدد فرع الميزة الخاص بك كفرع "compare"
5. حدد main كفرع "base"
6. انقر على "Create pull request"
كتابة أوصاف PR فعالة
يجب أن يشرح وصف PR الجيد ماذا تغير ولماذا:
العنوان: إضافة صفحة الاتصال لاستفسارات العملاء
الوصف:
## ماذا
- إنشاء صفحة contact.html جديدة
- إضافة نموذج اتصال مع التحقق من البريد الإلكتروني
- التكامل مع SendGrid API لتسليم البريد الإلكتروني
## لماذا
- طلب المستخدمون طريقة للاتصال بالدعم
- تقليل حجم رسائل البريد الإلكتروني للدعم بنسبة 30%
- يغلق #42
## الاختبار
- [x] التحقق من صحة النموذج يعمل بشكل صحيح
- [x] تم اختبار تسليم البريد الإلكتروني على الاختبار
- [x] تم التحقق من التصميم المتجاوب للهاتف المحمول
## لقطات الشاشة
[إرفاق لقطات شاشة ذات صلة]
نصيحة احترافية: استخدم كلمات رئيسية مثل "Closes #42" أو "Fixes #42" في وصف PR الخاص بك لإغلاق المشكلات ذات الصلة تلقائياً عند دمج PR.
قوالب طلبات السحب
أنشئ قالب PR لتوحيد الأوصاف عبر فريقك:
# إنشاء دليل .github
mkdir -p .github
# إنشاء قالب PR
cat > .github/pull_request_template.md <<EOF
## الوصف
[صف تغييراتك]
## نوع التغيير
- [ ] إصلاح خطأ
- [ ] ميزة جديدة
- [ ] تغيير كاسر
- [ ] تحديث التوثيق
## الاختبار
- [ ] الاختبارات تمر محلياً
- [ ] إضافة اختبارات جديدة
- [ ] اكتمل الاختبار اليدوي
## قائمة التحقق
- [ ] الكود يتبع إرشادات الأسلوب
- [ ] اكتملت المراجعة الذاتية
- [ ] تم تحديث التوثيق
- [ ] لا توجد تحذيرات جديدة
EOF
git add .github/pull_request_template.md
git commit -m "Add PR template"
git push
عملية مراجعة الكود
مراجعة الكود لا تقل أهمية عن كتابته:
كمراجع:
✓ فحص جودة الكود وقابليته للقراءة
✓ البحث عن أخطاء محتملة أو حالات حافة
✓ التحقق من أن الاختبارات كافية
✓ التأكد من تحديث التوثيق
✓ فحص الثغرات الأمنية
✓ النظر في الآثار على الأداء
إجراءات المراجعة:
- تعليق: طرح أسئلة أو اقتراح تحسينات
- موافقة: الكود يبدو جيداً، جاهز للدمج
- طلب تغييرات: يجب إصلاح المشكلات قبل الدمج
التعليق على طلبات السحب
يوفر GitHub عدة طرق للتعليق:
تعليق عام:
اكتب في علامة التبويب المحادثة للحصول على تعليقات عامة
تعليق مضمن:
انقر على أرقام الأسطر في علامة التبويب "Files changed" للتعليق على كود محدد
تعليق متعدد الأسطر:
انقر واسحب أرقام الأسطر للتعليق على كتل الكود
اقتراح:
استخدم بناء جملة الاقتراح لتغييرات الكود المباشرة
مثال على اقتراح كود:
```suggestion
function calculateTotal(items) {
return items.reduce((sum, item) => sum + item.price, 0);
}
```
هذا أكثر إيجازاً ويستخدم JavaScript الحديث.
طلب المراجعين
قم بتعيين أشخاص محددين لمراجعة PR الخاص بك:
# على واجهة مستخدم GitHub:
1. افتح طلب السحب الخاص بك
2. انقر على "Reviewers" في الشريط الجانبي الأيمن
3. ابحث وحدد أعضاء الفريق
4. انقر خارجاً للتأكيد
# سيتلقون إشعاراً للمراجعة
أفضل ممارسة: اطلب من 1-3 مراجعين اعتماداً على تعقيد التغييرات. عدد كبير جداً من المراجعين يمكن أن يبطئ العملية.
الرد على تعليقات المراجعة
عندما يطلب المراجعون تغييرات:
# قم بإجراء التغييرات المطلوبة
git checkout feature/add-contact-page
# تحرير الملفات...
git add .
git commit -m "Address review feedback: improve validation"
# دفع التغييرات (لا حاجة لإنشاء PR جديد)
git push
# يتم تحديث PR تلقائياً مع الالتزامات الجديدة
نصيحة تواصل: رد على كل تعليق مراجعة للإقرار بالتعليقات، حتى لو كان مجرد "تم ✓" أو "تم الإصلاح في [commit-hash]"
طلبات السحب المسودة
إنشاء PRs مسودة لكود قيد التطوير:
# عند إنشاء PR على GitHub:
1. انقر على القائمة المنسدلة "Create pull request"
2. حدد "Create draft pull request"
# الفوائد:
- يظهر العمل قيد التقدم
- يمنع الدمج العرضي
- لا يزال يسمح بالتعليقات والمناقشة
- التحويل إلى جاهز للمراجعة عند الانتهاء
استراتيجيات الدمج
يقدم GitHub ثلاث طرق لدمج PRs:
1. التزام الدمج (افتراضي):
- ينشئ التزام دمج مع جميع الالتزامات الفردية
- يحافظ على التاريخ الكامل
- يظهر الرسم البياني هيكل الفرع
الأمر: git merge feature-branch
2. ضغط ودمج:
- يجمع جميع الالتزامات في واحد
- تاريخ فرع رئيسي أنظف
- يفقد تفاصيل الالتزام الفردية
الأمر: git merge --squash feature-branch
3. إعادة التأسيس والدمج:
- يعيد تشغيل الالتزامات فوق الفرع الأساسي
- تاريخ خطي (لا التزامات دمج)
- تاريخ أنظف لكن يعيد كتابة الالتزامات
الأمر: git rebase main && git merge feature-branch
مهم: إعدادات المستودع الخاصة بك تحدد استراتيجيات الدمج المتاحة. يمكن للمسؤولين تمكين/تعطيل الخيارات في إعدادات المستودع → الخيارات → زر الدمج.
الدمج التلقائي والمتطلبات
إعداد المتطلبات قبل الدمج:
المتطلبات الشائعة:
- الحد الأدنى لعدد الموافقات (مثلاً، 2 مراجعين)
- يجب أن تمر فحوصات الحالة (اختبارات CI/CD)
- حل جميع المحادثات
- يجب أن يكون الفرع محدثاً مع القاعدة
- لا توجد تعارضات دمج
التمكين في:
الإعدادات → الفروع → قواعد حماية الفرع
إغلاق طلبات السحب
يمكن إغلاق PRs دون دمج:
# إغلاق PR دون دمج (على GitHub):
1. قم بالتمرير إلى أسفل PR
2. انقر على "Close pull request"
3. أضف تعليقاً يشرح السبب
# أسباب شائعة:
- التغييرات لم تعد مطلوبة
- PR مكرر
- نهج خاطئ
- العمل مهجور
أوامر طلب السحب (GitHub CLI)
إدارة PRs من سطر الأوامر:
# قم أولاً بتثبيت GitHub CLI: https://cli.github.com/
# إنشاء PR
gh pr create --title "Add feature" --body "Description"
# قائمة PRs
gh pr list
# عرض تفاصيل PR
gh pr view 123
# الخروج من PR محلياً
gh pr checkout 123
# مراجعة PR
gh pr review 123 --approve
gh pr review 123 --request-changes --body "Please fix..."
# دمج PR
gh pr merge 123 --squash
# إغلاق PR
gh pr close 123
تمرين عملي:
المهمة: إنشاء سير عمل طلب سحب
- إنشاء فرع جديد:
feature/update-readme - إجراء تغييرات على README.md (إضافة قسم "المساهمة")
- الالتزام ودفع التغييرات
- إنشاء طلب سحب على GitHub
- إضافة وصف مفصل باستخدام تنسيق القالب
- طلب مراجعة من زميل في الفريق (أو نفسك للتدريب)
- إضافة تعليق إلى PR الخاص بك
- دمج PR باستخدام "Squash and merge"
النتيجة المتوقعة: ستحصل على خبرة عملية مع سير عمل PR الكامل من الإنشاء إلى الدمج.
أفضل ممارسات طلب السحب
✓ احتفظ بـ PRs صغيرة ومركزة (أسهل للمراجعة)
✓ اكتب عناوين وأوصاف واضحة ووصفية
✓ اربط المشكلات ذات الصلة بالكلمات الرئيسية (Closes #42)
✓ اطلب مراجعات من أعضاء الفريق ذوي الصلة
✓ رد بسرعة على تعليقات المراجعة
✓ احتفظ بفرع PR محدثاً مع main
✓ حل جميع المحادثات قبل الدمج
✓ احذف الفرع بعد الدمج
✓ استخدم PRs المسودة للعمل قيد التقدم
✓ أضف لقطات شاشة لتغييرات واجهة المستخدم
الملخص
في هذا الدرس، تعلمت:
- طلبات السحب تمكّن المراجعة المنظمة للكود والتعاون
- سير عمل PR: فرع → التزام → دفع → إنشاء PR → مراجعة → دمج
- أوصاف PR الفعالة تشرح ماذا تغير ولماذا
- مراجعة الكود تشمل التعليق أو الموافقة أو طلب التغييرات
- ثلاث استراتيجيات دمج: التزام الدمج، الضغط، وإعادة التأسيس
- قوالب PR توحد عملية المراجعة
- PRs المسودة مفيدة لكود قيد التطوير
- GitHub CLI يمكّن إدارة PR من سطر الأوامر
التالي: في الدرس التالي، سنستكشف تفريع المستودعات والمساهمة في مشاريع المصدر المفتوح!