في هذا الدرس 6تصفّح المواضيع
يبدأ كل مستودع احترافي بملف توثيق واضح باسم README.md في مجلده الجذري؛ إذ تعرضه منصة GitHub تلقائياً كواجهة رئيسية للمشروع فور فتح صفحته، مما يجعله الانطباع الأول لأعضاء الفريق ومديري التوظيف والمستخدمين.
ويجب أن يجيب ملف README.md المتكامل عن أربعة أسئلة خلال ثوانٍ: ماذا يفعل هذا المشروع؟، وما المتطلبات المسبقة لتشغيله؟، وكيف أثبّته وأشغّله محلياً خطوة بخطوة؟، وكيف أشغّل الاختبارات؟
git add README.md
git commit -m "docs: add setup and test commands to README"
git pushوفق قوانين حقوق النشر الدولية، فإن نشر مستودع عام على GitHub دون ملف ترخيص LICENSE لا يجعله مفتوح المصدر قانونياً؛ بل يخضع افتراضياً لقاعدة جميع الحقوق محفوظة، مما يمنع الشركات والمطورين من استخدامه بأمان. وتمنح إضافة ملف ترخيص قياسي مثل MIT أو Apache-2.0 أو GPL-3.0 الصلاحيات القانونية الواضحة مع إخلاء المسؤولية.
وإلى جانب الترخيص، أضف ملف CONTRIBUTING.md لتوضيح قواعد تسمية الفروع وخطوات فتح طلبات السحب، وملف SECURITY.md لتوفير وسيلة آمنة للإبلاغ عن الثغرات الأمنية.
git add LICENSE CONTRIBUTING.md SECURITY.md
git status -s
git commit -m "docs: add MIT license and contributing guide"
git pushحتى المطورون المتمرسون قد ينفذون عن طريق الخطأ أمراً يرفع تعديلات مباشرة إلى الفرع main. ولفرض الانضباط الهندسي آلياً من جانب الخادم، فعّل قواعد حماية الفروع Branch Protection Rules على GitHub لحماية الفرع main:
- اشتراط فتح طلب سحب قبل الدمج مع إلزام الحصول على موافقة مراجع واحد أو أكثر.
- اشتراط نجاح فحوصات البناء
CI Status Checksلمنع دمج أي كود يفشل في الاختبارات. - حظر الرفع القسري
Block force pushesومنع حذف الفرع الرئيسي.
# When main is protected, direct push is rejected by GitHub;
# always create a feature branch and open a Pull Request:
git switch -c chore-ci-rules
git commit --allow-empty -m "chore: verify branch protection"
git push -u origin chore-ci-rulesإياك أن تكتب كلمات مرور قواعد البيانات أو مفاتيح API Keys أو مفاتيح التوقيع السرية مباشرة داخل ملفات الكود المصدري؛ بل اقرأ الأسرار من ملف بيئة محلي باسم .env، وأضف .env إلى ملف التجاهل .gitignore منذ اليوم الأول قبل تسجيل أول التزام في المشروع.
ولكي يعرف زملاؤك في الفريق أسماء المتغيرات البيئية المطلوبة لتشغيل التطبيق، أضف والتزم بملف قالب آمن باسم .env.example يحتوي على أسماء المتغيرات وقيم توضيحية وهمية فقط.
# Verify that .env is ignored by .gitignore:
git check-ignore -v .env
# Track only .gitignore and the safe .env.example template:
git add .gitignore .env.example
git commit -m "chore: ignore .env and add .env.example"ماذا تفعل إذا التزم أحد المطورين بالخطأ بملف .env حقيقي أو مفتاح سري ورفعه إلى GitHub؟ يظن المبتدئون أن إضافة التزام جديد يحذف الملف يكفي لحل المشكلة، لكن المفتاح السري يظل مكشوفاً بالكامل داخل الالتزام السابق في سجل git log! وتلتقط البرمجيات الآلية المفاتيح المنشورة خلال ثوانٍ.
اتبع خطة الاستجابة الفورية للحوادث بهذا الترتيب الصارم:
- إبطال المفتاح وتدويره فوراً
Revoke & Rotate: ادخل في اللحظة نفسها إلى لوحة تحكم المزود السحابي وعطّل المفتاح المتسرب وولّد مفتاحاً جديداً؛ إذ يُعتبر أي سر وصل إلى السحابة مخترقاً حكماً. - إيقاف تتبع الملف في الفهرس: نفّذ
git rm --cached .envوتأكد من وجوده في.gitignoreثم سجل الالتزام وارفعه.
# STEP 1: Revoke the leaked secret in the cloud provider!
# STEP 2: Untrack .env from Git while keeping local file:
git rm --cached .env
git add .gitignore
git commit -m "security: untrack .env after key rotation"
git pushتهانينا على إتمام منهج Git وGitHub الكامل المكوّن من 33 درساً! يجمع الجدول المرجعي الشامل التالي دورة العمل الاحترافية الكاملة عبر الوحدات السبع:
| مرحلة العمل | الأوامر الأساسية | القاعدة الذهبية |
|---|---|---|
| 1. الإعداد والبدء | git config --global، git init، git clone | اضبط هويتك وملف .gitignore شاملاً .env منذ اليوم الأول |
| 2. الالتزامات اليومية | git status -sb، git diff، git add -p، git commit | اكتب التزامات ذرية برسائل واضحة تشرح سبب التغيير |
| 3. التفريع والعزل | git switch -c <feat>، git stash | اعزل كل ميزة أو إصلاح في فرع مستقل عن main |
| 4. المزامنة والدمج | git fetch، git pull --rebase، git rebase -i | نظّف سجلك المحلي قبل رفعه ولا تعِد أساس التزامات مشتركة |
| 5. التراجع والإنقاذ | git restore، git reset --soft، git revert، git reflog | استخدم reset محلياً وrevert على الفروع المشتركة وreflog للإنقاذ |
| 6. الرفع والإصدار | git push -u، طلب السحب، git tag -a v1.0.0 | احمِ main بالمراجعة وفحوصات CI ووثّق الإصدارات بالوسوم |
ملخص الدرس
حصاد الدرسمراجعة مركّزة لأهم المفاهيم والقواعد الهندسية التي أتقنتها في هذا الدرس قبل التطبيق العملي
ماذا تعلّمت في هذا الدرس؟
ملخص الدرس وختام الدورة: وثّق كل مستودع بملفات README.md وLICENSE وCONTRIBUTING.md، واحمِ الفرع main بقواعد الحماية، وتجاهل .env مع الالتزام بالقالب .env.example، وأبطل فوراً أي مفتاح سري يتسرب للسحابة.
الخطوة التالية والدرس القادم
طبّق دورة عمل Git وGitHub المتكاملة التي أتقنتها في مشاريعك البرمجية ومساهماتك في المصادر المفتوحة وفرق العمل الهندسية!
سجّل الدخول لحفظ تقدمك
تابع إنجاز المواضيع والمصطلحات والمهام، وكمّل من آخر خطوة على أي جهاز.
المصطلحات4
راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.
- 01 Docs & Repo Security التوثيق وأمن المستودع
- جهّز مستودعاتك الاحترافية بملفات README.md وLICENSE وSECURITY.md، واحمِ الفرع الرئيسي بقواعد الحماية، وامنع تسرب المفاتيح والأسرار البرمجية.
- للمراجعة
- 02 Crafting Professional README بناء ملف توثيق README.md
- المفهوم الأساسي لدرس توثيق المستودعات الاحترافي وأمن الأسرار البرمجية في سير عمل Git وGitHub.
- للمراجعة
- 03 Licenses and CONTRIBUTING Docs تراخيص البرمجيات ودليل المساهمة
- التطبيق العملي المباشر لمفهوم تراخيص البرمجيات ودليل المساهمة.
- للمراجعة
- 04 Branch Protection for main قواعد حماية الفرع الرئيسي
- قواعد التحقق وأفضل الممارسات الخاصة بـ قواعد حماية الفرع الرئيسي.
- للمراجعة
لا توجد بطاقات تطابق البحث والتصفية.
اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.
الاختصارات4
راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.
- 01 DVCS DVCS
- Distributed Version Control System
- معمارية يمتلك فيها كل مطور نسخة محلية كاملة من تاريخ المستودع وكائناته.
- للمراجعة
- 02 SSH SSH
- Secure Shell
- بروتوكول شبكي مشفر يُستخدم للمصادقة الآمنة ونقل كائنات Git عبر المفاتيح.
- للمراجعة
- 03 PR PR
- Pull Request
- مقترح على GitHub لمراجعة واختبار ودمج التزامات فرع الميزة داخل الفرع الهدف.
- للمراجعة
- 04 CI CI
- Continuous Integration
- تشغيل الاختبارات وفحوصات البناء آلياً عند رفع الالتزامات أو فتح طلبات السحب.
- للمراجعة
لا توجد بطاقات تطابق البحث والتصفية.
اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.
مهامك قبل الاختبار
خطوة صغيرة كل مرة. وإنجاز تقدر ترجع له.
-
نفّذ أوامر الطرفية المشروحة في بناء ملف توثيق README.md داخل مستودع تجريبي محلي وافحص المخرجات.
-
بدّل بين الحالات الثلاث في المختبر التفاعلي ضمن قسم تراخيص البرمجيات ودليل المساهمة وقارن الأوامر والمخرجات.
تأشير المهمة إقرار منك بإتمامها، وليس تصحيحًا آليًا للكود. يُحفظ تقدمك في حسابك.
اختبر فهمك.
ووصلها للإتقان.
كل سؤال خطوة لقدّام. اختار، اكتب كود، وشوف نتيجتك فورًا.
أكمل المهام، واجمع كل الإجابات الصحيحة. أقل من 100%؟ راجع وأعد المحاولة.
الأسئلة متاحة للاطلاع. سجّل الدخول للتفاعل وحفظ تقدمك.
لمحة عن التحدي8 أسئلة تنتظرك ＋
أي ملف في جذر المستودع تعرضه منصة GitHub تلقائياً كصفحة توثيق رئيسية للمشروع؟
يُعرض ملف README.md تلقائياً في الصفحة الرئيسية للمستودع على GitHub.
إن نشر مستودع عام على GitHub بدون ملف ترخيص (LICENSE) يمنح الجميع تلقائياً صلاحية قانونية كاملة لاستخدام الكود وتعديله.
خطأ؛ فبدون ملف LICENSE تطبق قاعدة جميع الحقوق محفوظة افتراضياً، ويجب إضافة ملف ترخيص لجعل المشروع مفتوح المصدر قانونياً.
ما الغرض من تفعيل قواعد حماية الفروع (Branch Protection Rules) على الفرع "main" في GitHub؟
تمنع قواعد الحماية الرفع المباشر أو القسري إلى main وتشترط مراجعة طلبات السحب واجتياز فحوصات CI قبل الدمج.
كيف يتعامل الفريق الاحترافي مع ملف الأسرار ".env" وملف القالب ".env.example" في Git؟
يُضاف الملف .env إلى .gitignore لمنع تتبع الأسرار الحقيقية، بينما يُلتزم بملف القالب .env.example بقيم توضيحية فقط.
ما الإجراء الأول والأكثر حرجاً الذي يجب اتخاذه فوراً إذا رُفع مفتاح API سري أو كلمة مرور بالخطأ إلى GitHub؟
إبطال المفتاح المتسرب وتوليد مفتاح جديد فوراً من لوحة تحكم المزود، لأن أي سر يُرفع للسحابة يُعد مخترقاً حكماً.
يؤدي حذف ملف ".env" المتسرب في التزام جديد إلى مسح المفتاح السري نهائياً من الالتزامات السابقة في سجل git log.
خطأ؛ فحذف الملف في التزام جديد يبقيه موجوداً ومكشوفاً بالكامل داخل لقطة الالتزام السابق في تاريخ Git.
أي أمر يوقف تتبع ملف ".env" في فهرس Git دون حذفه من قرصك الصلب المحلي؟
يزيل الأمر git rm --cached .env الملف من فهرس التتبع مع الإبقاء عليه في مجلد العمل المحلي.
إن الجمع بين نظافة .gitignore وفروع الميزات ومراجعة طلبات السحب وفحوصات CI ووسوم الإصدارات يشكل دورة عمل Git القياسية المتكاملة في صناعة البرمجيات.
صواب؛ فهذه الممارسات المتكاملة تضمن بقاء المشاريع البرمجية نظيفة وآمنة وقابلة للتعاون والتوسع.