الدرس 6 من 10

اكتمل 60%

التعاون عبر GitHub

أتقن طلبات السحب (Pull Requests) والمشكلات (Issues) والنقاشات (Discussions) للتعاون بفعالية مع المطورين الآخرين.

التعاون عبر GitHub

أحدث GitHub ثورة في التعاون ضمن تطوير البرمجيات. سيعلّمك هذا الدرس كيفية استخدام أدوات GitHub التعاونية: طلبات السحب (pull requests) والمشكلات (issues) والنقاشات (discussions) وغيرها الكثير للعمل بفعالية ضمن فريق.

نظرة عامة على التعاون

المشكلات (Issues): إدارة المهام والأخطاء

ما هي الـ Issue؟

الـ issue هي تذكرة تُستخدم من أجل:

الإبلاغ عن الأخطاء
اقتراح ميزات جديدة
طرح الأسئلة
تنظيم المهام

إنشاء Issue

# قالب issue للإبلاغ عن خطأ
**وصف الخطأ**
وصف واضح وموجز للمشكلة.

**خطوات إعادة إنتاج الخطأ**
1. انتقل إلى '...'
2. انقر على '....'
3. مرر الصفحة إلى '....'
4. لاحظ الخطأ

**السلوك المتوقع**
وصف لما كان يجب أن يحدث.

**لقطات الشاشة**
أضف لقطات شاشة إن أمكن.

**البيئة:**
- نظام التشغيل: [مثال: iOS]
- المتصفح: [مثال: chrome, safari]
- الإصدار: [مثال: 22]

إدارة الـ Issues

# باستخدام GitHub CLI
gh issue create --title "Bug dans le login" --body "Description détaillée"
gh issue list
gh issue view 123
gh issue close 123

# إسناد issue
gh issue edit 123 --add-assignee username

# إضافة labels
gh issue edit 123 --add-label bug,priority-high

الـ Labels والتنظيم

الـ Labels الافتراضية:

bug: شيء لا يعمل
enhancement: ميزة جديدة أو طلب جديد
documentation: تحسينات على التوثيق
good first issue: مناسبة للمساهمين الجدد
help wanted: مطلوب مساعدة إضافية

الـ Labels المخصصة:

priority-high (أحمر)
priority-medium (برتقالي)
priority-low (أخضر)
frontend (أزرق)
backend (بنفسجي)

طلبات السحب (Pull Requests): اقتراح التعديلات

سير عمل Pull Request

# 1. إنشاء Fork للمستودع (عبر واجهة GitHub)
# 2. استنساخ الـ fork الخاص بك
git clone https://github.com/VOTRE-USERNAME/projet.git
cd projet

# 3. إنشاء فرع
git checkout -b feature/nouvelle-fonctionnalite

# 4. التطوير وإنشاء commit
echo "nouveau code" > feature.js
git add feature.js
git commit -m "feat: add new feature"

# 5. دفع الفرع
git push origin feature/nouvelle-fonctionnalite

# 6. إنشاء Pull Request عبر واجهة GitHub

تشريح Pull Request

# قالب Pull Request

## الوصف
ملخص التغييرات والدافع وراءها.

## نوع التغيير
- [ ] إصلاح خطأ (تغيير لا يكسر التوافق ويصلح مشكلة)
- [ ] ميزة جديدة (تغيير لا يكسر التوافق ويضيف ميزة)
- [ ] تغيير كاسر للتوافق (إصلاح أو ميزة قد تعطّل الوظائف الحالية)
- [ ] توثيق

## كيف تم اختبار ذلك؟
وصف الاختبارات التي أُجريت.

## قائمة التحقق:
- [ ] يتبع الكود الخاص بي إرشادات المشروع
- [ ] أجريت مراجعة ذاتية لكودي
- [ ] علّقت على كودي، خاصة في المواضع الصعبة
- [ ] أجريت التغييرات المقابلة في التوثيق
- [ ] لا تُنتج تغييراتي تحذيرات (warnings) جديدة
- [ ] أضفت اختبارات تثبت فعالية الإصلاح
- [ ] الاختبارات الجديدة والحالية تنجح محليًا

أوامر GitHub CLI الخاصة بـ PR

# إنشاء PR
gh pr create --title "Add new feature" --body "Description détaillée"

# عرض قائمة الـ PR
gh pr list

# عرض PR
gh pr view 123

# عمل checkout لـ PR من أجل الاختبار
gh pr checkout 123

# دمج PR
gh pr merge 123 --merge  # أو --squash أو --rebase

# إغلاق PR
gh pr close 123

مراجعة الكود (Code Review)

عملية المراجعة

قراءة الكود: فهم التغييرات
الاختبار محليًا: التحقق من أنه يعمل
ملاحظات بنّاءة: تعليقات مفيدة
الموافقة أو طلب تعديلات

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

# تعليق عام
هذا النهج مثير للاهتمام، لكن هل فكرت في استخدام X بدلًا من Y؟

# اقتراح كود
```suggestion
function calculateTotal(items) {
    return items.reduce((sum, item) => sum + item.price, 0);
}

سؤال

لماذا اخترت هذه الطريقة بدلًا من الـ API الأصلية؟

Nitpick (ملاحظة طفيفة)

nit: مسافة ناقصة بعد الفاصلة


### أفضل ممارسات المراجعة

**بالنسبة للمراجع (reviewer):**
- كن بنّاءً ومحترمًا
- اشرح «لماذا» وراء اقتراحاتك
- وافق سريعًا على الـ PR الجيدة
- اختبر التغييرات المهمة

**بالنسبة للمؤلف:**
- ردّ على التعليقات
- طبّق الاقتراحات المناسبة
- اطلب التوضيح عند الحاجة
- اشكر المراجعين على مراجعاتهم

## الـ Forks والمساهمات

### عمل Fork لمشروع

```bash
# 1. عمل Fork عبر واجهة GitHub
# 2. استنساخ الـ fork الخاص بك
git clone https://github.com/VOTRE-USERNAME/projet-fork.git
cd projet-fork

# 3. إضافة المستودع الأصلي كـ remote
git remote add upstream https://github.com/AUTEUR-ORIGINAL/projet.git

# 4. التحقق من الـ remotes
git remote -v

المزامنة مع الـ upstream

# جلب التغييرات من الـ upstream
git fetch upstream

# دمج التغييرات في فرع main الخاص بك
git checkout main
git merge upstream/main

# الدفع إلى الـ fork الخاص بك
git push origin main

سير عمل المساهمة

# 1. المزامنة مع الـ upstream
git fetch upstream
git checkout main
git merge upstream/main

# 2. إنشاء فرع لمساهمتك
git checkout -b fix/bug-description

# 3. التطوير
# ... التعديلات ...

# 4. إنشاء commit
git add .
git commit -m "fix: resolve issue with user authentication"

# 5. الدفع إلى الـ fork الخاص بك
git push origin fix/bug-description

# 6. إنشاء Pull Request نحو الـ upstream

نقاشات GitHub (Discussions)

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

Q&A: أسئلة وأجوبة
Ideas: اقتراح أفكار
General: نقاشات عامة
Show and tell: مشاركة الإنجازات

إنشاء نقاش

# مثال على نقاش من نوع "Ideas"
**العنوان:** إضافة وضع داكن إلى التطبيق

**الوصف:**
أقترح إضافة وضع داكن لتحسين تجربة المستخدم،
خاصة عند الاستخدام الليلي.

**المزايا:**
- تقليل إجهاد العين
- توفير البطارية على شاشات OLED
- توجه حديث في التصميم

**أسئلة:**
- ما لوحة الألوان التي ينبغي استخدامها؟
- هل نحتاج إلى مفتاح تبديل تلقائي بناءً على الوقت؟
- كيف نتعامل مع التوافق مع السمات (themes) الحالية؟

إدارة المشاريع عبر GitHub

GitHub Projects

# تنظيم مشروع
الأعمدة المعتادة:
- Backlog
- To Do
- In Progress
- In Review
- Done

# الأتمتة
- نقل البطاقات تلقائيًا بحسب الأحداث
- ربط الـ issues والـ PR بالبطاقات
- التصفية حسب المُسنَد إليه والـ label والـ milestone

الـ Milestones

# تنظيم الـ issues حسب الإصدار/السبرنت
Milestone: Version 2.0
- Issue #45: إضافة مصادقة OAuth
- Issue #46: تحسين الأداء
- Issue #47: إصلاح خطأ التنقل

Due date: 2024-03-15
Progress: 2/3 issues مغلقة (67%)

الإشعارات والإشارات (Mentions)

نظام الإشعارات

# أنواع الإشعارات
- الإشارات (@username)
- الإسنادات
- المراجعات المطلوبة
- التعليقات على الـ PR/Issues الخاصة بك
- النشاط في المستودعات التي تتابعها

# إدارة الإشعارات
Settings > Notifications
- إشعارات البريد الإلكتروني
- إشعارات الويب
- إشعارات الجوال

الإشارات والفرق

# الإشارة إلى مستخدم
@username هل يمكنك إلقاء نظرة على هذه الـ PR؟

# الإشارة إلى فريق
@org/frontend-team هذه الـ PR تخص واجهة المستخدم

# الإشارة ضمن commit
git commit -m "fix: resolve login issue

Fixes #123
cc @maintainer-team"

الأمان والصلاحيات

مستويات الوصول

Read: الاستنساخ والقراءة
Triage: إدارة الـ issues والـ PR
Write: الدفع (push) والدمج (merge)
Maintain: إدارة المستودع دون صلاحيات مدمّرة
Admin: وصول كامل

حماية الفروع (Branch protection)

# قواعد الحماية لفرع main
- Require pull request reviews before merging
- Require status checks to pass before merging
- Require branches to be up to date before merging
- Require conversation resolution before merging
- Restrict pushes that create files larger than 100MB

تمارين عملية

التمرين 1: أول مساهمة

# 1. اعمل Fork لمشروع مفتوح المصدر بسيط
# 2. استنسخ الـ fork الخاص بك
git clone https://github.com/VOTRE-USERNAME/projet-fork.git

# 3. أنشئ فرعًا
git checkout -b docs/improve-readme

# 4. حسّن التوثيق
echo "## Installation\n\n\`\`\`bash\nnpm install\n\`\`\`" >> README.md

# 5. أنشئ commit ثم ادفع
git add README.md
git commit -m "docs: improve installation instructions"
git push origin docs/improve-readme

# 6. أنشئ Pull Request

التمرين 2: إدارة الـ Issues

# 1. أنشئ عدة issues في مستودعك
gh issue create --title "Bug: Login ne fonctionne pas" --label bug
gh issue create --title "Feature: Ajouter mode sombre" --label enhancement
gh issue create --title "Docs: Améliorer le README" --label documentation

# 2. أسند ونظّم
gh issue edit 1 --add-assignee VOTRE-USERNAME
gh issue edit 2 --add-label "good first issue"

# 3. اربط PR بـ issue
git checkout -b fix/login-bug
# ... التطوير ...
git commit -m "fix: resolve login authentication issue

Fixes #1"

التمرين 3: مراجعة الكود

# 1. أنشئ PR تحتوي على كود قابل للتحسين
echo "function add(a,b){return a+b}" > math.js
git add math.js
git commit -m "add math function"
git push origin feature/math

# 2. أنشئ الـ PR واطلب مراجعة
gh pr create --title "Add math utilities" --reviewer ami-reviewer

# 3. ردّ على التعليقات وحسّن الكود
echo "function add(a, b) {
  if (typeof a !== 'number' || typeof b !== 'number') {
    throw new Error('Both arguments must be numbers');
  }
  return a + b;
}" > math.js

git add math.js
git commit -m "improve: add input validation to math function"
git push origin feature/math

الأدوات والتكاملات

GitHub Desktop

واجهة رسومية من أجل:

عرض التغييرات
إنشاء الـ commits
إدارة الفروع
المزامنة مع GitHub

VS Code + GitHub

إضافات مفيدة:

GitHub Pull Requests and Issues
GitLens
GitHub Copilot

تكاملات CI/CD

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '16'
      - run: npm install
      - run: npm test

أفضل الممارسات التعاونية

التواصل

كن واضحًا في أوصافك
استخدم القوالب (templates) للـ issues والـ PR
ردّ بسرعة على المراجعات
وثّق قراراتك المهمة

التنظيم

استخدم labels متسقة
نظّم باستخدام milestones
أسند المسؤوليات
أغلق الـ issues التي تم حلها

الكود

commits ذرّية (atomic) ووصفية
فروع قصيرة ومركّزة
اختبارات للميزات الجديدة
توثيق محدّث

استكشاف الأخطاء وإصلاحها في العمل التعاوني

تعارضات الدمج في PR

# 1. المزامنة مع الفرع الرئيسي
git fetch origin
git checkout feature-branch
git merge origin/main

# 2. حل التعارضات
# ... تحرير يدوي ...

# 3. إنشاء commit لحل التعارضات
git add .
git commit -m "resolve merge conflicts"
git push origin feature-branch

PR عالقة بسبب الـ checks

# التحقق من status checks
gh pr checks

# إعادة تشغيل الـ checks عند الحاجة
gh pr ready --undo  # تحويلها إلى draft
gh pr ready         # تحويلها إلى ready

مصادر إضافية

توثيق GitHub

أدوات من جهات خارجية

Conventional Commits: معيار لصياغة الرسائل
Semantic Release: أتمتة إصدار النسخ
All Contributors: تقدير المساهمين

الخاتمة

يتجاوز التعاون على GitHub مجرد مشاركة الكود بكثير. فهو منظومة متكاملة تسهّل التواصل والتنظيم وجودة تطوير البرمجيات. وسيجعلك إتقان هذه الأدوات أكثر كفاءة في مشاريعك التعاونية.

في الدرس القادم، سنتعمق في حل التعارضات، وهو جانب حاسم في العمل الجماعي.

وقت القراءة المقدّر: 25 دقيقة
المستوى: متوسط
الخطوة السابقة: مقدمة إلى GitHub
الخطوة التالية: حل التعارضات