Contributing to Discourse development

توثيق المساهمة
1

:bookmark: تم تصميم هذا الدليل لأولئك الذين يرغبون في المساهمة في مشروع Discourse مفتوح المصدر، ويوضح الإعداد والاصطلاحات اللازمة للتعاون الفعال.

:person_raising_hand: مستوى المستخدم المطلوب: بينما يمكن لأي شخص المساهمة في الكود، ستحتاج إلى أن تكون على دراية بـ Ruby و JavaScript.

ملخص

ستغطي هذه الوثائق ما يلي:

  • إعداد بيئة التطوير الخاصة بك
  • فهم من أين تبدأ المساهمة
  • إنشاء المكونات الإضافية (plugins) لـ Discourse والعمل عليها
  • المساهمة في نواة (core) Discourse
  • اصطلاحات الترميز التي يجب اتباعها
  • إرسال مساهماتك على GitHub

إعداد بيئة التطوير

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

معرفة من أين تبدأ

Discourse هو مشروع كبير، وفهم تقنياته الأساسية مثل Ruby و JavaScript أمر ضروري. للحصول على إرشادات حول كيفية البدء، راجع دليل المبتدئين.

إنشاء المكونات الإضافية لـ Discourse والعمل عليها

توفر المكونات الإضافية (Plugins) طريقة لفهم الأجزاء الداخلية لـ Discourse في أجزاء يمكن إدارتها وتسمح لك ببدء المساهمة بالكود بسهولة. ابدأ بـ:

للحصول على الإلهام، استكشف الأفكار الشائعة في Feature و Plugin > Extras.

المساهمة في نواة Discourse

يتم إدارة كود نواة Discourse في مستودع النواة على GitHub.

توقيع اتفاقية ترخيص المساهمة (CLA)

قبل المساهمة، اقرأ ووقع على اتفاقية ترخيص مساهمة المنتديات الإلكترونية (Electronic Discourse Forums Contribution License Agreement). لا يمكن للفريق قبول طلبات السحب (PRs) بشكل قانوني من المستخدمين الذين لم يوقعوا على اتفاقية ترخيص المساهمة.

الإحماء بمهام للمبتدئين

استكشف وسم pr-welcome للمهام الجيدة للبدء.

العمل من خلال قائمة الأخطاء

قم بإصلاح الأخطاء من قائمة الأخطاء المفتوحة مرتبة حسب الإعجابات. اترك ملاحظة إذا كنت تعمل على خطأ - إذا لم تكمله، اترك أي ملاحظات ذات صلة لشخص آخر لمتابعة عملك.

المساعدة في مواضيع الميزات

ساهم بالتفاصيل والنماذج الأولية لـ طلبات الميزات للمساعدة في عملية الموافقة عليها. تذكر، لن يتم تضمين كل ميزة في النواة.

تحسين الأداء

نرحب بطلبات السحب التي تعزز أداء جانب العميل أو الخادم، مع التركيز على المجالات ذات التأثير العالي مثل التحميل الأولي للصفحة الرئيسية أو عرض الموضوع.

تحسين المشاريع التي يديرها Discourse

ساهم في مشاريع مفتوحة المصدر أخرى يديرها Discourse. تشمل بعض المشاريع البارزة:

اصطلاحات الترميز

التسمية أمر بالغ الأهمية (CRITICAL)

اسعَ لتحقيق تطابق بنسبة 100٪ بين المصطلحات المستخدمة على الموقع وأسماء الفئات والأعمدة في قاعدة البيانات (على سبيل المثال، “posts”).

التوافق مع أحدث إصدارات التبعيات أمر بالغ الأهمية (CRITICAL)

تأكد من التوافق مع أحدث الإصدارات المستقرة للمكتبات مثل Rails و Ruby و Ember. اختبر التراجعات (regressions) عند تحديث التبعيات.

مساهمات الاختبار فقط مرحب بها

مساهمات الاختبار مرحب بها، خاصة للعمليات وإجراءات المتحكم (controller actions) التي لم يتم اختبارها. تجنب المحاكاة (mocking) إلا إذا كان ذلك ضروريًا للغاية.

مساهمات إعادة الهيكلة فقط غير مرحب بها (NOT welcome)

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

إرسال الكود على GitHub

سير العمل خطوة بخطوة

  1. استنساخ مستودع Discourse:

    git clone https://github.com/discourse/discourse.git

  2. إنشاء فرع جديد:

    cd discourse
git checkout -b new_discourse_branch

  3. الترميز:

    • التزم باصطلاحات الكود الحالية التي تجدها في الكود.
    • قم بتضمين الاختبارات وتأكد من نجاحها.
    • أشر إلى المناقشات ذات الصلة على منتدى ميتا Discourse.

  4. اتبع اصطلاحات الترميز:

    • مسافتان، لا علامات جدولة (tabs)
    • لا مسافات بيضاء زائدة في النهاية، يجب ألا تحتوي الأسطر الفارغة على مسافات
    • استخدم مسافات حول العوامل، وبعد الفواصل، والنقطتين، والفواصل المنقوطة، وحول { وقبل }
    • لا توجد مسافة بعد ( أو [ أو قبل ] أو )
    • استخدم صيغة تجزئة Ruby 1.9: فضل { a: 1 } على { :a => 1 }
    • فضل class << self; def method; end على def self.method لطرق الفئة
    • فضل { ... } على do ... end للكتل ذات السطر الواحد، وتجنب استخدام { ... } للكتل متعددة الأسطر
    • تجنب return عندما لا يكون مطلوبًا

  5. الالتزام (Commit):

    git commit -m "ملخص موجز للتغيير" -m "وصف مفصل للتغيير"

    لا تترك رسالة التزام فارغة أبدًا - هذا دليل مفيد لكتابة رسائل الالتزام. يجب أن تبدأ الرسالة بملخص قصير (بحد أقصى 72 حرفًا) في السطر الأول، يليه سطر فارغ، ثم وصف أكثر تفصيلاً للتغيير. يمكنك استخدام صيغة ماركداون (markdown) للتنسيق البسيط إذا لزم الأمر.

    تأكد من إضافة بادئة لعناوين الالتزام وفقًا لـ اصطلاحات Discourse.

    5 (أ). التدقيق اللغوي (Linting):
    يتم تدقيق كود JavaScript باستخدام eslint وشروط التنسيق لـ prettier. يتم تدقيق Ruby باستخدام RuboCop. يتم تشغيل كل هذه الفحوصات تلقائيًا في إجراءات GitHub في كل مرة تنشئ فيها طلب سحب لـ Discourse.

    • يوصى بشدة بتثبيت خطافات git الخاصة بالالتزام المسبق (pre-commit git hooks) باستخدام lefthook. سيتم تشغيل هذا تلقائيًا في كل مرة تقوم فيها بالالتزام في نواة Discourse، وسيُثير مشاكل مع اللغات والقوالب المختلفة قبل أن تقوم بدفعها وتضطر إلى انتظار تشغيل GitHub CI. قم بتشغيل هذا في جذر مشروعك:
      mkdir .git/hooks
npx lefthook install

  6. تحديث فرعك:

    git fetch origin
git rebase origin/main

  7. التشعيب (Fork):

    git remote add mine git@github.com:<your-username>/discourse.git

  8. الدفع إلى الريموت الخاص بك:

    git push mine new_discourse_branch

  9. إصدار طلب سحب:

    • انتقل إلى المستودع الخاص بك على GitHub.
    • انقر على “Pull Request”.
    • اكتب اسم فرعك في حقل الفرع.
    • انقر على “Update Commit Range”.
    • تحقق من التغييرات في علامات التبويب “Commits” و “Files Changed”.
    • قدم عنوانًا ووصفًا.
    • انقر على “Send pull request”.

    قبل إرسال طلب سحب، قم بتنظيف السجل، وراجع التزاماتك وقم بدمج التغييرات والإصلاحات الطفيفة في الالتزامات المقابلة. يمكنك دمج الالتزامات باستخدام أمر إعادة الأساس التفاعلي (interactive rebase command):

git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i

< يفتح المحرر ويسمح لك بتغيير سجل الالتزام >
< اتبع التعليمات في أسفل المحرر >

git push -f mine new_discourse_branch
  1. الاستجابة للملاحظات:
    • كن مستجيبًا للملاحظات ومستعدًا لتنفيذ التغييرات المقترحة.
    • تذكر، الملاحظات تعني أن عملك ذو قيمة ومقصود للإدراج.

شكرًا لك على المساهمة في مشروع Discourse مفتوح المصدر!

73 إعجابًا