Contributing to Discourse development

[Discourse]

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

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

ملخص

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

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

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

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

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

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

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

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

توفر المكونات الإضافية (Plugins) طريقة لفهم الأجزاء الداخلية لـ 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 Forums Contribution License Agreement). لا يمكن للفريق قبول طلبات السحب (PRs) قانونيًا من المستخدمين الذين لم يوقعوا على اتفاقية ترخيص المساهمة.

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

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

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

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

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

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

تحسين الأداء

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   cd discourse
   git checkout -b new_discourse_branch
   

3. الترميز:

   • التزم باتفاقيات الترميز الحالية التي تجدها في الكود.
   • قم بتضمين الاختبارات وتأكد من اجتيازها.
   • أشر إلى المناقشات ذات الصلة على منتدى ميتا 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 "ملخص موجز للتغيير" -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):

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

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

git push -f mine new_discourse_branch

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

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

[Moin]

هل تم إزالة هذا عن قصد؟

@Discourse

5) Commit

لكل commit، يرجى كتابة ملخص قصير (بحد أقصى 72 حرفًا) في السطر الأول متبوعًا بسطر فارغ ثم وصف أكثر تفصيلاً للتغيير. استخدم صيغة markdown للتنسيق البسيط.

لا تنسَ البادئة! تأكد من اتباع اتفاقية بادئة الـ commit الخاصة بـ Discourse GitHub لعنوان الـ commit الخاص بك.

لا تترك رسالة الـ commit فارغة أبدًا! قدم وصفًا مفصلاً وواضحًا وكاملاً لـ commit الخاص بك! انظر “كيفية كتابة رسالة Git commit” للحصول على نصائح رائعة.

---

@Discourse

و أروع إضافة لـ Discourse لم يتم إنشاؤها بعد.

هذا لم يعد يعمل

[hugh (Hugh Lashbrooke)]

شكراً @Moin - لقد قمت بتصحيح هذا في الموضوع!

[justinm]

مرحباً، هل هناك أي إرشادات حول كيفية طلب مراجعة طلب سحب (PR)؟ لقد قدمت طلبين للسحب ويبدو أن فريق Discourse قد فاته للأسف. يحدث هذا، وهذا لا بأس به. ولكن يبدو أنه لا توجد أي وثائق حول كيفية تنبيه شخص ما في الفريق باحترام.

[sam (Sam Saffron)]

أتفهمك. كقاعدة عامة، أعتقد أن إعادة نشر المنشور في طلب السحب (PR) بعد شهر أمر مقبول. يمكنك أيضًا فتح موضوع (أو الرد على موضوع ذي صلة موجود على Meta) بشأنه.

[justinm]

مرحباً سام، لقد حاولت بالفعل دفع طلب سحب (هنا) ويبدو أن الدفعات لا تعمل بنفس الطريقة على GitHub كما تعمل هنا (لا يتم دفعها إلى أعلى القائمة).

سأنتقل إلى فئة Dev في المستقبل. قد يكون من الجيد ذكر هذه الفئة صراحةً في المنشور الأصلي (إما في الخطوة رقم 10 أو قبلها)

[NateDhaliwal]

إذا قمنا بتقديم طلب سحب (PR) يحتاج إلى توطين، فهل نضع سلاسل YAML فارغة في ملفات config/locales؟