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

[Discourse]

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

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

الملخص

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

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

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

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

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

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

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

إنشاء وإدارة الإضافات (Plugins)

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

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

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

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

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

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

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

التدرب بمهام مبدئية

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

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

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

المساعدة في مواضيع الميزات (Feature Topics)

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

تحسين الأداء

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

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

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

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

اتفاقيات الكتابة البرمجية (Coding Conventions)

التسمية أمر حاسم (CRITICAL)

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

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

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

المساهمات المخصصة للاختبار موضع ترحيب

تُرحب المساهمات المخصصة للاختبار، خاصة للعمليات وإجراءات التحكم (Controller Actions) غير المختبرة. تجنب استخدام المحاكاة (Mocking) إلا إذا كان ذلك ضرورياً للغاية.

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

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

تقديم الكود على GitHub

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

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

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

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

   cd discourse
   git checkout -b new_discourse_branch
   

3. الكتابة البرمجية:

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

4. اتبع اتفاقيات الكتابة البرمجية:

   • مسافتان متباعدتان، بدون علامات تبويب (Tabs)
   • لا توجد مسافات بيضاء زائدة في نهاية الأسطر، يجب ألا تحتوي الأسطر الفارغة على مسافات
   • استخدم مسافات حول المشغلات (Operators)، وبعد الفواصل، والنقطتين الرأسيتين، والفواصل المنقوطة، حول { وقبل }
   • لا توجد مسافة بعد ( أو [ أو قبل ] أو )
   • استخدم صيغة الهاش في Ruby 1.9: يفضل استخدام { a: 1 } بدلاً من { :a => 1 }
   • يفضل استخدام class << self; def method; end بدلاً من def self.method للدوال الصفية (Class Methods)
   • يفضل استخدام { ... } بدلاً من 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.

   • يُنصح بشدة بتثبيت خطوط الخطاف (Git Hooks) الخاصة بنا قبل الالتزام باستخدام lefthook. سيعمل هذا تلقائياً في كل مرة تقوم فيها بالالتزام في النواة الأساسية لـ Discourse، وسيشير إلى المشكلات في اللغات والقوالب المختلفة قبل دفعها (Push) وإضطرارك للانتظار حتى تعمل اختبارات 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. الدفع (Push) إلى المستودع البعيد الخاص بك:

   git push mine new_discourse_branch
   

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

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

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

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

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

git push -f mine new_discourse_branch

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

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