المساهمة في تطوير Discourse

[Discourse]

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

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

الملخص

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

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

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

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

• جميع المنصات: تثبيت Discourse للتطوير باستخدام Docker
• Mac OS X: دليل المبتدئين لتثبيت Discourse على macOS للتطوير
• Linux (Ubuntu): دليل المبتدئين لتثبيت Discourse على Ubuntu للتطوير
• Windows: دليل المبتدئين لتثبيت Discourse على Windows 10 للتطوير

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

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

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

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

• Developing Discourse Plugins - Part 1 - Create a basic plugin
• (deprecated) Plugin outlet locations theme component

للحصول على الإلهام، استكشف الأفكار الشائعة في #feature و #plugin:extras.

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

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

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

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

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

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

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

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

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

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

تحسين الأداء

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

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

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

• Logster - عارض سجلات بواجهة مستخدم رسومية ويب
• Message Bus - محرك لتفاعلات الموقع المباشرة
• Rack Mini Profiler - أداة تشخيص
• Discourse API - مستهلك واجهة برمجة التطبيقات (API)
• Discourse Docker - محرك توزيع Discourse
• WP Discourse - مكون إضافي لـ WordPress
• Memory Profiler - أداة تحليل لأداء Ruby
• Ember Performance - مجموعة اختبارات أداء Ember

اتفاقيات الترميز

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

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

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

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

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

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

المساهمات الخاصة بإعادة الهيكلة فقط غير مرحب بها

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

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

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

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

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

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

   cd discourse
   git checkout -b new_discourse_branch
   

3. الترميز:

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

4. اتباع اتفاقيات الترميز:

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

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

   git commit -m "A short summary of the change" -m "A detailed description of the change"
   

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

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

   5 (أ). التدقيق (Linting):
   يتم تدقيق كود JavaScript باستخدام eslint وتنسيقه باستخدام prettier. يتم تدقيق Ruby باستخدام RuboCop وتنسيقه باستخدام Syntax Tree. يتم تدقيق SCSS/CSS باستخدام stylelint. يتم تدقيق قوالب Ember باستخدام ember-template-lint. يتم تشغيل كل هذه الفحوصات تلقائيًا في إجراءات GitHub كلما أنشأت طلب سحب لـ Discourse.

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

     pnpm 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):

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

# يفتح المحرر ويسمح لك بتغيير سجل الالتزام 
# اتبع التعليمات في الجزء السفلي من المحرر 

git push -f mine new_discourse_branch

10. الاستجابة للملاحظات:
    • كن مستجيبًا للملاحظات ومستعدًا لتنفيذ التغييرات المقترحة.
    • تذكر، الملاحظات تعني أن عملك له قيمة والهدف هو تضمينه.

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