هيكل مستودع GitHub الجيد: الملفات والفروع ورسائل الالتزام التي تجعل مشروعك احترافياً

مقدمة

المستودع واجهة مشروعك أمام المساهمين وأصحاب العمل. مستودع منظم يقول: «هذا المشروع يُعتنى به». وفوضى المجلدات ورسائل commit مثل «fix» و«update» تقول العكس. التنظيم الجيد لا يحتاج وقتاً كبيراً إن بدأت به مبكراً.

أهداف التعلم

• تنظيم مجلدات المستودع بوضوح.
• إضافة الملفات القياسية التي يتوقعها الزوار.
• كتابة رسائل commit مفيدة.
• العمل بالفروع وطلبات الدمج مع فحوص تلقائية.

1. هيكل المجلدات

my-project/
├─ src/                 # الكود المصدري
├─ tests/               # الاختبارات
├─ docs/                # توثيق ولقطات شاشة
├─ scripts/             # سكربتات مساعدة (نشر، ترحيل)
├─ .github/
│  ├─ workflows/ci.yml  # فحوص تلقائية
│  ├─ ISSUE_TEMPLATE/
│  └─ pull_request_template.md
├─ .env.example
├─ .gitignore
├─ LICENSE
├─ README.md
├─ CONTRIBUTING.md
└─ SECURITY.md

القاعدة: من يفتح المستودع لأول مرة يجب أن يعرف أين الكود وأين الاختبارات وكيف يشغل المشروع.

2. الملفات القياسية

• README.md: ما المشروع، لقطة شاشة، طريقة التشغيل.
• LICENSE: شروط الاستخدام.
• CONTRIBUTING.md: كيف يساهم الآخرون (إعداد البيئة، أسلوب الكود، طريقة فتح طلب دمج).
• SECURITY.md: كيف يبلَّغ عن ثغرة بشكل خاص بدل فتح Issue عام.
• .gitignore: يمنع رفع node_modules و.env وملفات البناء. استخدم قوالب github/gitignore.

3. رسائل commit واضحة

رسالة جيدة تشرح ماذا ولماذا:

fix(auth): منع تسجيل الدخول بكلمة مرور فارغة

كان التحقق يقبل سلسلة فارغة عند وجود مسافات فقط بسبب
عدم استخدام trim(). أضيف اختبار يغطي الحالة.

صيغة Conventional Commits (feat: fix: docs: refactor: test: chore:) تسهّل قراءة التاريخ وتوليد سجلات التغيير. وقاعدة مهمة: commit واحد لتغيير منطقي واحد، لا «أصلحت كل شيء».

4. الفروع وطلبات الدمج

git switch -c feat/expense-export
# ... تعديلات صغيرة مع commits واضحة
git push -u origin feat/expense-export
# ثم افتح Pull Request على GitHub

• الفرع الرئيسي (main) يبقى صالحاً للنشر دائماً.
• كل ميزة أو إصلاح في فرع منفصل وطلب دمج يُراجع.
• فعّل قواعد حماية الفرع: منع الدفع المباشر إلى main، واشتراط نجاح الفحوص ومراجعة واحدة على الأقل.

قالب طلب الدمج يساعد المراجع:

## ماذا يغير هذا الطلب؟
## كيف اختبرته؟
## لقطات شاشة (للتغييرات المرئية)

5. أتمتة الفحوص

ملف .github/workflows/ci.yml يشغّل الاختبارات والتدقيق مع كل طلب دمج، فيكتشف الأخطاء قبل الدمج. وأضف Dependabot لتحديث التبعيات وفحص أسرار مثل gitleaks.

6. الإصدارات والوسوم

git tag -a v1.0.0 -m "الإصدار الأول"
git push origin v1.0.0

استخدم الترقيم الدلالي (MAJOR.MINOR.PATCH)، وأنشئ «Release» على GitHub يلخص التغييرات للمستخدمين.

تمرين عملي

1. رتّب أحد مستودعاتك بالهيكل أعلاه، وأضف CONTRIBUTING.md وSECURITY.md.
2. أعد كتابة رسائل آخر 3 commits بصيغة واضحة في فرع جديد (git rebase -i محلياً على فرعك أنت فقط، لا على تاريخ مشترك).
3. فعّل حماية الفرع main وأضف خط CI بسيطاً، ثم افتح طلب دمج وتأكد أن الفحص يعمل.

أخطاء شائعة

• رسائل «update» و«wip» و«fix stuff».
• commit ضخم يخلط عدة تغييرات.
• الدفع المباشر إلى main دون مراجعة.
• إعادة كتابة تاريخ فرع مشترك بـ force push.
• غياب .gitignore فتُرفع ملفات البناء والأسرار.

الخلاصة

مجلدات واضحة، ملفات قياسية، رسائل commit تشرح السبب، فروع وطلبات دمج محمية بفحوص تلقائية. هذه العادات تجعل مشروعك سهل الفهم والمساهمة.

مصادر مقترحة

• conventionalcommits.org.
• توثيق GitHub: «About protected branches» و«Creating a default community health file».
• كتاب Pro Git (متاح مجاناً على git-scm.com).