أول مرة تفتح فيها صفحة مشروع على GitHub ترى شيئين: قائمة ملفات ومجلدات، وتحتها نصًا يشرح ما هو المشروع. الأول هو المستودع، والثاني هو README. الأول بيت الشيفرة، والثاني اللافتة المعلقة على بابه.

المستودع (Repository) هو مجلد المشروع مع السجل الكامل لكل التغييرات التي طرأت عليه. كل ملف وكل تغيير، ومن أجراه ولماذا، يُسجل في المستودع. والأداة التي تحفظ هذا السجل هي عادة Git.

ماذا يخزن المستودع بالضبط؟#

لنفترض أنك تعمل على إضافة ووردبريس. دون مستودع ستحفظ النسخ بأسماء مثل plugin-final وplugin-final-2 وplugin-final-new، وبعد شهر لن تتذكر أيها كان يعمل.

مع المستودع لديك مجلد واحد. في كل مرة تسجل تغييرًا (commit) يحفظ Git لقطة من المشروع مع وصف قصير. ومتى احتجت يمكنك أن ترى متى تغير سطر ما، أو تعود إلى نسخة سابقة، أو تجرب شيئًا على فرع منفصل. إذا كانت هذه المفاهيم جديدة عليك فاقرأ Git للمبتدئين.

يحتوي المستودع عادة على:

  • شيفرة المشروع وملفاته: ما تبنيه فعلًا.
  • السجل: كل الـ commits في المجلد المخفي .git.
  • الفروع (branches): خطوط تطوير متوازية.
  • ملفات متعارف عليها: README وLICENSE و.gitignore وأحيانًا CONTRIBUTING.

المستودع المحلي والمستودع البعيد#

يمكن أن يوجد المستودع في مكانين، وغالبًا يوجد في الاثنين:

النوعأين يوجدفيمَ يفيد
محلي (local)على حاسوبكالعمل اليومي، الـ commit، التجربة دون إنترنت
بعيد (remote)على خدمة مثل GitHub أو GitLab أو خادمك الخاصالنسخ الاحتياطي، العمل الجماعي، النشر على الخادم

بالأمر clone تحصل على نسخة محلية من المستودع البعيد، وبالأمر push ترسل تغييراتك، وبالأمر pull تجلب تغييرات الآخرين:

Bash
git clone https://github.com/USERNAME/my-plugin.git
cd my-plugin
git add .
git commit -m "Add settings page"
git push

في العمل الجماعي، بدل الدفع مباشرة إلى الفرع الرئيسي، تفتح عادة طلب دمج (Pull Request) لتتم مراجعة الشيفرة؛ والتفاصيل في GitHub للعمل الجماعي. ويمكن أن يكون المستودع البعيد وسيلة نقل الشيفرة إلى الاستضافة أيضًا؛ راجع نشر الموقع باستخدام Git على استضافة مشتركة.

ما هو README ولماذا هو مهم إلى هذا الحد؟#

README ملف نصي في جذر المستودع، اسمه عادة README.md. الامتداد md يعني أنه مكتوب بلغة Markdown، وتعرضه GitHub والخدمات المشابهة منسقًا أسفل قائمة الملفات.

يُكتب README لثلاثة أشخاص:

  1. الزائر لأول مرة: يريد أن يفهم في ثوانٍ ما هو المشروع وهل يفيده.
  2. من يريد استخدامه: يبحث عن أوامر التثبيت ومثال بسيط.
  3. أنت بعد ستة أشهر: وقد نسيت كيف كنت تشغل المشروع.

المشروع الذي لا README له يبقى خفيًا عن معظم الناس مهما كانت شيفرته ممتازة.

أقسام README الجيد#

لا يلزم أن يكون README طويلًا، لكن يجب أن يضم هذه الأقسام بهذا الترتيب تقريبًا:

القسمماذا تكتب
الاسم وجملة واحدةما هو المشروع وما المشكلة التي يحلها، في جملة واحدة
الميزاتمن ثلاث إلى ست ميزات رئيسية في قائمة
المتطلباتالحد الأدنى من إصدار PHP أو ووردبريس أو Node.js أو غيرها
التثبيتأوامر أو خطوات دقيقة قابلة للنسخ
الاستخداممثال قصير يعمل فعلًا
الإعداداتالإعدادات ومتغيرات البيئة دون القيم السرية الحقيقية
المساهمةإذا كنت ترحب بالمساعدة، كيف يبلغون عن الأخطاء
الترخيصالنوع الترخيص والإشارة إلى ملف LICENSE

إذا كان للمشروع واجهة مستخدم، فلقطة شاشة واحدة للصفحة الرئيسية تشرح أكثر من عدة فقرات.

نصائح لملف README أفضل#

  • اكتب الجملة الأولى لشخص غريب: «إضافة لإرسال رسائل تأكيد الطلب النصية في WooCommerce» أفضل من «أداة قوية ومرنة».
  • اجعل الأوامر قابلة للنسخ: كل أمر يجب تشغيله يوضع في كتلة شيفرة لا في وسط جملة.
  • قدّم مثالًا حقيقيًا: مخرجات نموذجية أو مقطع شيفرة يعمل دون تعديل.
  • حدّث README مع الشيفرة: كلما تغيرت طريقة التثبيت أو الإعدادات، عدّل README في الـ commit نفسه.
  • استعن بالذكاء الاصطناعي للمسودة لا للادعاءات: أعطه بنية الملفات واطلب مسودة، ثم راجع كل جملة بنفسك.
أمر موجّه
هذه بنية المجلدات وملف composer.json لمشروع Laravel. اكتب ملف README بالعربية يضم هذه الأقسام: جملة تعريفية، الميزات، المتطلبات، خطوات التثبيت بأوامر دقيقة، مثال استخدام واحد، إعدادات ملف env دون قيم حقيقية، والترخيص. لا تخمن أي شيء غير موجود في الملفات؛ اكتب مكانه «يُستكمل».

ملفات أخرى بجوار README#

ليس README الملف المتعارف عليه الوحيد في المستودع. هناك ملفات أخرى تتعرف عليها خدمات مثل GitHub، ويجيب كل منها عن سؤال محدد:

الملفالسؤال الذي يجيب عنه
LICENSEما الذي يُسمح للآخرين بفعله بهذه الشيفرة؟
.gitignoreما الملفات التي يجب ألا تدخل المستودع؟
CHANGELOG.mdما الذي تغير في كل إصدار؟
CONTRIBUTING.mdإذا أردت المساعدة، من أين أبدأ؟
.env.exampleما الإعدادات المطلوبة، دون القيم السرية الحقيقية؟

لمشروع شخصي صغير يكفي README و.gitignore. وكلما صار المشروع أكثر انفتاحًا والفريق أكبر، زادت قيمة بقية الملفات. والمهم أن يشير README إلى هذه الملفات لا أن يكرر محتواها؛ هكذا تُحدَّث كل معلومة في مكان واحد فقط.

أخطاء شائعة#

  • وضع كلمات المرور والمفاتيح في المستودع: ملف .env ومفاتيح API وكلمة مرور قاعدة البيانات يجب ألا تُضاف إلى أي commit. ضعها في .gitignore واذكر في README أسماء المتغيرات فقط. إذا أضفتها بالخطأ فحذفها من آخر نسخة لا يكفي لأنها تبقى في السجل؛ غيّر المفتاح.
  • README فارغ أو افتراضي: النص الذي تضعه الخدمة عند إنشاء المستودع هو اسم المشروع فقط ولا يقول شيئًا.
  • عدم توثيق المتطلبات: عبارة «لا يتثبت» تعني غالبًا أن إصدار PHP أو إضافة مطلوبة لم تُذكر.
  • إضافة مجلدات يمكن إعادة بنائها: مجلدات مثل vendor وnode_modules يمكن إعادة إنشائها عبر Composer وnpm؛ مكانها في .gitignore.
  • غياب ملف LICENSE في مشروع عام: دون ترخيص لا يعرف الآخرون قانونيًا هل يُسمح لهم باستخدام الشيفرة.

الخلاصة#

  • المستودع هو مجلد المشروع مع سجل تغييراته الكامل.
  • لديك عادة نسخة محلية على حاسوبك ونسخة بعيدة على GitHub أو خدمة مشابهة.
  • README أول ما يراه الجميع، ويجب أن يقول ما هو المشروع وكيف يُثبت وكيف يُستخدم.
  • أقسام README الأساسية: التعريف، الميزات، المتطلبات، التثبيت، الاستخدام، الإعدادات، الترخيص.
  • كلمات المرور والمفاتيح لا تدخل المستودع أبدًا؛ استخدم .gitignore.
  • حدّث README مع الشيفرة باستمرار.