المساهمة في تطوير 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 أمر ضروري. للحصول على إرشادات حول كيفية البدء، راجع دليل المبتدئين.

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

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

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

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

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

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

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

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

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

استكشف وسم 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. اختبر وجود أي انتكاسات عند تحديث التبعيات.

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

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

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

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

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

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

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

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

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

   cd discourse
   git checkout -b new_discourse_branch
   

3. البرمجة:

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

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

   • مسافتان متباعدتان، بدون علامات تبويب
   • لا توجد مسافات بيضاء زائدة في نهاية السطر، لا يجب أن تحتوي الأسطر الفارغة على مسافات
   • استخدام مسافات حول المشغلات، بعد الفواصل، والنقطتين المنقوطين، وفواصل النقاط، حول { وقبل }
   • لا توجد مسافة بعد ( أو [ أو قبل ] أو )
   • استخدام صيغة Hash الخاصة بـ 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.

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

     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”.

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

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

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

git push -f mine new_discourse_branch

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

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