أدلة المشاريع

قالب README على GitHub لمشروع مفتوح المصدر

يجيب README المفيد على GitHub بسرعة عن أربعة أسئلة: ماذا يفعل المشروع، ولمن هو، وكيف أجرّبه، وأين أحصل على المساعدة؟ استخدم قالب Markdown أدناه نقطة انطلاق، ثم استبدل كل نص نائب بمعلومات تحقّقت منها في مشروعك.

فريق تحرير GitHubStart · آخر تحديث

انسخ قالب README هذا بصيغة Markdown

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

# [اسم المشروع]

[جملة واحدة: المشكلة والمستخدم المستهدف والنتيجة.]

## مثال
[اعرض مدخلًا صغيرًا ومخرجه المتوقع، أو أضف لقطة شاشة.]

## البدء السريع
المتطلبات: [بيئة التشغيل/الإصدار والخدمات المطلوبة].

```sh
# استبدل هذا السطر بأمر التثبيت الذي تحققت منه.
# استبدل هذا السطر بأبسط أمر ينتج نتيجة مفيدة.
```

النتيجة المتوقعة: [ما ينبغي أن يراه القارئ].

## الإعداد
[الإعدادات المطلوبة وقيم نموذجية آمنة ومكان تخزين الأسرار.]

## متى تستخدمه
- [حالة استخدام محددة]
- [حالة استخدام ثانية]

## القيود
[مدخلات غير مدعومة أو مستوى النضج أو قيود الأداء أو المنصة.]

## الوثائق والمساعدة
[أضف رابط الوثائق واشرح أين يمكن طرح سؤال.]

## المساهمة
راجع [CONTRIBUTING.md](CONTRIBUTING.md).
أبلغ عن مشكلة قابلة لإعادة الإنتاج عبر علامة التبويب Issues في المستودع.

## الترخيص
راجع [LICENSE](LICENSE).

كيّف المثال مع نوع المستودع

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

لا تجعل لقطة الشاشة الشرح الوحيد لواجهة API؛ ينبغي أن يستطيع القرّاء نسخ الشيفرة. وبالمقابل، قد يستفيد التطبيق المرئي من لقطة شاشة تصف بوضوح ما يفعله المستخدم. استخدم أمثلة فعلية من الإصدار الذي توزّعه حاليًا.

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

راجع README قبل مشاركته

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

افتح روابط الوثائق والصور من صفحة المستودع. تأكد من تطابق أسماء ملفات المساهمة والترخيص مع مستودعك، واحذف الروابط المعطّلة. README قصير ودقيق أفضل من قالب مبهر مليء بوعود لم تنفّذها.

  • احذف النصوص النائبة والادعاءات غير المدعومة.
  • لا تضع رموز وصول حقيقية أو كلمات مرور أو عناوين URL خاصة في الأمثلة.
  • تحقّق من أن المخرج المتوقع يطابق الإصدار المنشور.
  • أخبر القرّاء بالمعلومات الواجب تضمينها عند الإبلاغ عن مشكلة.

استخدم README موجزًا لإطلاق مشروعك

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

أسئلة شائعة

هل هذا README لمستودع أم لملف شخصي؟

هذا القالب لمستودع برمجي. يعرّف README للملف الشخصي بشخص، ويحتاج إلى أقسام مختلفة مثل أعماله وتفضيلاته للتواصل.

هل أضيف شارات النجوم في الأعلى؟

فقط إذا كانت تفيد القارئ. أبقِ الغرض والبدء السريع بارزين. لا تغني الشارة عن شرح ما يفعله المشروع.

هل يمكنني استخدام القالب لمشروع خاص؟

نعم. استبدل روابط الدعم العامة بقنوات المساعدة الفعلية لفريقك، واشرح متطلبات الوصول، ولا تضع بيانات الاعتماد في المستند.

المراجع