Git و GitHub
قضايا GitHub
قضايا GitHub
GitHub Issues هو نظام تتبع قوي مدمج في كل مستودع. إنه مثالي لتتبع الأخطاء، وتخطيط الميزات، وإدارة المهام، وتسهيل المناقشات. القضايا هي واحدة من أهم أدوات التعاون على GitHub وتستخدمها الفرق من جميع الأحجام، من المطورين الأفراد إلى المشاريع الكبيرة مفتوحة المصدر.
ما هي قضايا GitHub؟
القضايا هي تذاكر تتبع الأفكار والتحسينات والمهام أو الأخطاء لمشروعك:
يمكن استخدام القضايا لـ:
✓ الإبلاغ عن الأخطاء وتتبعها
✓ طلبات الميزات والتخطيط
✓ إدارة المهام وقوائم المهام
✓ تحسينات التوثيق
✓ الأسئلة والمناقشات
✓ تخطيط الإصدار والمعالم
✓ تتبع خارطة طريق المشروع
الميزات الرئيسية:
- دعم Markdown للتنسيق الغني
- العلامات للتصنيف
- المُعينون للمسؤولية
- المعالم للتجميع
- التعليقات للمناقشة
- الإشارة المرجعية المتقاطعة مع الالتزامات/PRs
- البحث والتصفية
- إشعارات البريد الإلكتروني
نصيحة محترف: القضايا عامة في المستودعات العامة ومرئية للجميع. استخدم القضايا بشفافية لبناء ثقة المجتمع وتشجيع المساهمات.
إنشاء قضية
إنشاء القضايا أمر مباشر:
عبر واجهة ويب GitHub:
1. انتقل إلى مستودعك
2. انقر على علامة تبويب "Issues"
3. انقر على زر "New issue"
4. أدخل عنواناً وصفياً
5. اكتب وصفاً تفصيلياً
6. أضف علامات (اختياري)
7. عيّن لشخص ما (اختياري)
8. اربط بمعلم (اختياري)
9. انقر على "Submit new issue"
عبر GitHub CLI:
# إنشاء قضية بسيطة
gh issue create --title "Bug: Login fails" --body "Description here"
# إنشاء قضية تفاعلية
gh issue create
# إنشاء بعلامات ومُعينين
gh issue create --title "Feature request" \
--body "Details..." \
--label "enhancement" \
--assignee username
كتابة أوصاف القضايا الفعالة
القضية المكتوبة بشكل جيد توفر الوقت وتحصل على ردود أسرع:
قالب تقرير الأخطاء:
**الوصف**
وصف واضح للخطأ
**خطوات إعادة الإنتاج**
1. اذهب إلى '...'
2. انقر على '...'
3. مرر لأسفل إلى '...'
4. شاهد الخطأ
**السلوك المتوقع**
ما الذي يجب أن يحدث
**السلوك الفعلي**
ما يحدث بالفعل
**لقطات الشاشة**
إذا كان ذلك قابلاً للتطبيق، أضف لقطات شاشة
**البيئة**
- نظام التشغيل: macOS 13.0
- المتصفح: Chrome 118
- الإصدار: 2.1.0
**سياق إضافي**
أي معلومات أخرى ذات صلة
قالب طلب الميزة:
**بيان المشكلة**
صف المشكلة التي ستحلها هذه الميزة
**الحل المقترح**
صف الحل المقترح
**الحلول البديلة**
صف البدائل التي فكرت فيها
**الفوائد**
من سيستفيد وكيف؟
**ملاحظات التنفيذ**
اعتبارات فنية (اختياري)
**أمثلة**
روابط لتطبيقات مشابهة
أفضل ممارسة: استخدم عناوين واضحة ووصفية. "زر تسجيل الدخول لا يعمل على الهاتف المحمول" أفضل من "خطأ" أو "من فضلك أصلح هذا".
قوالب القضايا
قوالب القضايا تعمل على توحيد كيفية إبلاغ المساهمين عن القضايا:
إنشاء قوالب القضايا:
1. أنشئ دليل .github/ISSUE_TEMPLATE/
2. أضف ملفات القوالب:
- bug_report.md
- feature_request.md
- custom_template.md
مثال bug_report.md:
---
name: Bug Report
about: Report a bug to help us improve
title: '[BUG] '
labels: bug
assignees: ''
---
## وصف الخطأ
وصف واضح لما هو الخطأ.
## خطوات إعادة الإنتاج
1. الخطوة الأولى
2. الخطوة الثانية
3. شاهد الخطأ
## السلوك المتوقع
ما كنت تتوقع أن يحدث.
## لقطات الشاشة
إذا كان ذلك قابلاً للتطبيق، أضف لقطات شاشة.
## البيئة
- نظام التشغيل: [مثل: macOS]
- الإصدار: [مثل: 1.0.0]
البديل: قوالب YAML (موصى به):
أنشئ: .github/ISSUE_TEMPLATE/bug_report.yml
name: Bug Report
description: File a bug report
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
شكراً للإبلاغ عن خطأ!
- type: textarea
id: description
attributes:
label: وصف الخطأ
description: وصف واضح للخطأ
placeholder: أخبرنا بما حدث خطأ
validations:
required: true
- type: dropdown
id: severity
attributes:
label: الخطورة
options:
- حرج
- رئيسي
- ثانوي
validations:
required: true
العلامات: تنظيم القضايا
العلامات تصنف وتصفي القضايا بفعالية:
علامات GitHub الافتراضية:
bug - شيء ما لا يعمل
documentation - تحسينات التوثيق
duplicate - هذه القضية موجودة بالفعل
enhancement - ميزة جديدة أو طلب
good first issue - جيد للمبتدئين
help wanted - يحتاج إلى اهتمام إضافي
invalid - هذا لا يبدو صحيحاً
question - معلومات إضافية مطلوبة
wontfix - لن يتم العمل على هذا
أمثلة العلامات المخصصة:
علامات الأولوية:
- priority: high (أحمر)
- priority: medium (برتقالي)
- priority: low (أصفر)
علامات الحالة:
- status: needs-review (أرجواني)
- status: in-progress (أزرق)
- status: blocked (أحمر)
علامات النوع:
- type: frontend (أخضر)
- type: backend (أزرق)
- type: database (أرجواني)
إدارة العلامات:
# عبر واجهة الويب:
Issues ← Labels ← New label أو Edit
# عبر GitHub CLI:
gh label create "priority: high" --color FF0000
gh label list
gh label delete "old-label"
# أضف علامة للقضية:
gh issue edit 123 --add-label "bug,priority: high"
ترميز الألوان: استخدم ألواناً متسقة: أحمر للعاجل/الأخطاء، أخضر للتحسينات، أزرق للمهام، أصفر للأسئلة. هذا يساعد في المسح البصري السريع.
المعالم: تجميع القضايا
المعالم تجمع القضايا ذات الصلة نحو هدف مشترك:
استخدامات المعالم الشائعة:
- إصدارات الإصدار (v1.0، v2.0، v2.1)
- دورات السباق (Sprint 1، Sprint 2)
- مراحل المشروع (Alpha، Beta، Launch)
- الأهداف الزمنية (Q1 2024، إصدار ديسمبر)
إنشاء المعالم:
عبر الويب: Issues ← Milestones ← New milestone
- العنوان: v2.0 Release
- تاريخ الاستحقاق: 2024-12-31
- الوصف: ميزات وأخطاء للإصدار 2.0
عبر CLI:
gh api repos/:owner/:repo/milestones \
-f title="v2.0 Release" \
-f due_on="2024-12-31T23:59:59Z"
تعرض المعالم التقدم بصرياً بنسبة الإكمال بناءً على القضايا المغلقة مقابل المفتوحة.
المُعينون: تفويض المسؤولية
عيّن القضايا لأعضاء الفريق لتوضيح الملكية:
تعيين القضايا:
# مُعين واحد
انقر على القضية ← Assignees ← حدد الشخص
# مُعينون متعددون (Teams/Pro)
يمكنك تعيين ما يصل إلى 10 أشخاص لكل قضية
# عبر CLI:
gh issue edit 123 --assignee username1,username2
# عيّن لنفسك:
gh issue edit 123 --assignee @me
# أزل المُعين:
gh issue edit 123 --remove-assignee username
ملاحظة: يمكن تعيين متعاوني المستودع فقط للقضايا. لا يمكن تعيين المساهمين الخارجيين، لكن يمكنهم التعليق والمساهمة.
ربط القضايا بالالتزامات وطلبات السحب
اربط القضايا بالكود الذي يحلها:
الإشارة إلى القضايا في الالتزامات:
# فقط اذكر القضية (لا تغلقها)
git commit -m "Update login validation, see #123"
# الإشارة إلى قضايا متعددة
git commit -m "Fix bugs #123 #456 #789"
# الربط بقضية في مستودع آخر
git commit -m "Fix user/repo#123"
الإغلاق التلقائي للقضايا بالكلمات الرئيسية:
# هذه الكلمات الرئيسية تغلق القضية عند دمج PR:
close #123
closes #123
closed #123
fix #123
fixes #123
fixed #123
resolve #123
resolves #123
resolved #123
# مثال التزام:
git commit -m "Fix login validation
This commit resolves the authentication bug
reported by multiple users.
Fixes #123"
الإشارة في طلبات السحب:
عند إنشاء PR، اذكر القضايا في الوصف:
This PR addresses #123 and partially fixes #456.
## التغييرات
- تحديث منطق المصادقة
- إضافة التحقق من المدخلات
- تحسين رسائل الخطأ
Closes #123
Related to #456
ربط القضايا بـ PRs:
في الشريط الجانبي للقضية ← Development ← Link PR
نصيحة محترف: استخدم "Closes #123" في وصف PR (وليس رسالة الالتزام) لتتبع أفضل. ستغلق القضية تلقائياً عند دمج PR.
مراجع القضايا والإشارات
ينشئ GitHub روابط تلقائية عندما تشير إلى القضايا:
بناء جملة الإشارة:
#123 - قضية في نفس المستودع
user/repo#123 - قضية في مستودع آخر
@username - ذكر مستخدم (يتلقى إشعاراً)
أين تعمل المراجع:
- أوصاف القضايا
- التعليقات
- رسائل الالتزام
- أوصاف طلبات السحب
- تعليقات مراجعة الكود
- سلاسل المناقشة
مثال تعليق:
أعتقد أن هذا يتعلق بـ #45 و #67.
@john هل يمكنك مراجعة هذا؟
انظر أيضاً user/other-repo#123 للسياق.
البحث وتصفية القضايا
يوفر GitHub قدرات بحث قوية:
الفلاتر الأساسية:
# فلاتر مدمجة (انقر في علامة تبويب Issues):
- القضايا المفتوحة
- قضاياك (المُعينة لك)
- القضايا التي أنشأتها
- القضايا التي تذكرك
بناء جملة البحث:
is:issue is:open - القضايا المفتوحة
is:issue is:closed - القضايا المغلقة
label:bug - القضايا مع علامة bug
assignee:username - مُعين لمستخدم
author:username - أنشأها مستخدم
mentions:username - تذكر مستخدم
milestone:"v2.0" - في معلم
no:label - بدون أي علامات
no:assignee - قضايا غير مُعينة
created:>2024-01-01 - أنشئت بعد التاريخ
updated:<2024-01-01 - حُدثت قبل التاريخ
دمج الفلاتر:
is:open label:bug assignee:@me
is:issue label:enhancement milestone:"v2.0"
is:open no:assignee label:"good first issue"
بحث CLI:
# سرد جميع القضايا المفتوحة
gh issue list
# تصفية حسب العلامة
gh issue list --label bug
# تصفية حسب المُعين
gh issue list --assignee @me
# تصفية حسب الحالة
gh issue list --state closed
# البحث بالنص
gh issue list --search "login bug"
# تحديد النتائج
gh issue list --limit 20
المشاريع: تنظيم القضايا
توفر مشاريع GitHub لوحات على نمط Kanban للقضايا:
إنشاء المشاريع:
1. انتقل إلى علامة تبويب Projects في المستودع
2. انقر على "New project"
3. اختر القالب:
- عرض اللوحة (Kanban)
- عرض الجدول (جدول بيانات)
- عرض خارطة الطريق (الجدول الزمني)
4. أضف القضايا إلى المشروع
5. نظم في الأعمدة (To Do، In Progress، Done)
أتمتة المشروع:
- إضافة تلقائية للقضايا الجديدة
- نقل تلقائي عند تغيير الحالة
- إغلاق تلقائي عند دمج PR
- سير عمل مخصص
إدارة إشعارات القضايا
تحكم في كيفية تلقي تحديثات القضايا:
مستويات الإشعارات:
Watch - إشعارات جميع الأنشطة
Participating - فقط @mentions والمُعينة
Ignore - لا إشعارات
تخصيص الإشعارات:
Settings ← Notifications ← Customize
- إشعارات البريد الإلكتروني
- إشعارات الويب
- دفع الهاتف المحمول (تطبيق GitHub Mobile)
- ملخص مجدول (يومي/أسبوعي)
إلغاء الاشتراك من القضية:
انقر على "Unsubscribe" في الشريط الجانبي للقضية
تمرين عملي:
التدرب على قضايا GitHub:
- أنشئ 5 قضايا مختلفة في مستودع الاختبار الخاص بك:
- 1 تقرير خطأ
- 1 طلب ميزة
- 3 عناصر مهام
- أنشئ علامات مخصصة: "priority: high"، "status: in-progress"، "type: frontend"
- طبق العلامات المناسبة على قضاياك
- أنشئ معلماً باسم "v1.0" وأضف القضايا إليه
- عيّن نفسك لقضيتين
- قم بتغيير كود والتزم مع "Fixes #1" لإغلاق قضية
- أضف تعليقات على القضايا باستخدام @mentions و #references
- جرب البحث:
is:open label:bug assignee:@me - أنشئ قالب قضية لمستودعك
أفضل ممارسات القضايا
✓ افعل:
- اكتب عناوين واضحة ووصفية
- قم بتضمين خطوات إعادة الإنتاج للأخطاء
- أضف العلامات ذات الصلة فوراً
- ابحث قبل إنشاء نسخ مكررة
- استخدم القوالب عند توفرها
- أشر إلى القضايا ذات الصلة
- أغلق القضايا عند حلها
- اشكر المساهمين
✗ لا تفعل:
- استخدم عناوين غامضة مثل "خطأ" أو "مشكلة"
- أنشئ قضايا ضخمة تتبع أشياء متعددة
- اترك القضايا تصبح قديمة دون تحديثات
- استخدم القضايا للأسئلة (استخدم Discussions)
- أغلق القضايا قبل الأوان
- كن وقحاً أو ازدرائياً
- تجاهل قوالب القضايا
الملخص
في هذا الدرس، تعلمت:
- قضايا GitHub تتبع الأخطاء والميزات والمهام بفعالية
- قوالب القضايا توحد تقارير الأخطاء وطلبات الميزات
- العلامات تنظم وتصنف القضايا حسب النوع والأولوية والحالة
- المعالم تجمع القضايا نحو أهداف الإصدار
- المُعينون يوضحون من هو المسؤول عن كل قضية
- يمكن إغلاق القضايا تلقائياً باستخدام الكلمات الرئيسية في الالتزامات/PRs
- البحث والتصفية القوية تساعد في العثور على القضايا ذات الصلة
- المشاريع توفر لوحات Kanban للتنظيم البصري
التالي: في الدرس التالي، سنستكشف طلبات السحب - الطريقة الأساسية لاقتراح التغييرات والتعاون على GitHub!