contributions.md

دليل المساهمة

• تقارير الأخطاء
• أسئلة الدعم
• نقاش التطوير الجوهري
• أي فرع؟
• الملفات المترجمة (Compiled Assets)
• الثغرات الأمنية
• تنسيق الكود
  • توثيق PHP
  • أداة StyleCI
• القواعد السلوكية

تقارير الأخطاء

لتشجيع التعاون النشط، لارافيل تشجع وبقوة طلبات السحب (pull requests)، بالإضافة لتقارير الأخطاء. ويمكن أيضاً إرسال "تقارير الأخطاء" بشكل طلب سحب (pull request) يحتوي على اختبار فشل. سيتم مراجعة طلبات السحب فقط عندما يتم تعليمها كـ"جاهزة للمراجعة" ("ready for review") وليست في حالة "مسودة" ("draft") وبعد اجتياز جميع الاختبارات للميزات الجديدة المضافة. سيتم إغلاق طلبات السحب العالقة وغير النشطة التي تركت في حالة "المسودة" بعد بضعة أيام.

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

تذكر، يتم إنشاء تقارير الأخطاء أملاً بأن الآخرين الذين يواجهون نفس المشكلة سيكونون قادرين على التعاون معك في حلها. لا تتوقع بأن تقرير الخطأ سوف يبحث في النشاطات تلقائياً أو أن الآخرين سيهبون لإصلاحه. إنشاء تقرير بالخطأ يأتي في صالحك أنت و الآخرين للبدء في مسار إصلاح المشكلة. إذا كنت تريد المشاركة، يمكنك المساعدة بإصلاح أي مشكلة مدرجة في أدوات تعقب المشكلات الخاصة بنا. يجب عليك أن تكون قد سجلت الدخول بغيت هاب (GitHub) لرؤية جميع مشكلات لارافيل.

شيفرة المصدر (source code) الخاصة بلارافيل تتم إداراتها على غيت هاب (GitHub)، ومستودعاتهم لكل مشاريع لارافيل هي:

• تطبيق لارافيل (Laravel Application)
• رسومات لارافيل (Laravel Art)
• توثيق لارافيل (Laravel Documentation)
• لارافيل داسك (Laravel Dusk)
• لارافيل كاشيير سترايب (Laravel Cashier Stripe)
• لارافيل كاشيير بادل (Laravel Cashier Paddle)
• لارافيل_ايكو (Laravel Echo)
• لارافيل اينفوي (Laravel Envoy)
• إطار عمل لارافيل (Laravel Framework)
• لارافيل هومستيد (Laravel Homestead)
• سكربتات بناء لارافيل هومستيد (Laravel Homestead Build Scripts)
• لارافيل هورايزن (Laravel Horizon)
• لارافيل جيت ستريم (Laravel Jetstream)
• لارافيل باسبورت (Laravel Passport)
• لارافيل سيل (Laravel Sail)
• لارافيل سانكتوم (Laravel Sanctum)
• لارافيل سكاوت (Laravel Scout)
• لارافيل سوشيلايت (Laravel Socialite)
• لارافيل تيليسكوب (Laravel Telescope)
• موقع لارافيل (Laravel Website)

أسئلة الدعم

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

• GitHub Discussions
• Laracasts Forums
• Laravel.io Forums
• StackOverflow
• Discord
• Larachat
• IRC

نقاش التطوير الجوهري

يمكنك اقتراح ميزات أو تحسينات لسلوك لارافيل الموجود في مستودع (repository) إطار عمل لارافيل مجلس المناقشة في غيت هاب (GitHub). اذا كنت تود اقتراح ميزة جديدة، رجاءً كن مستعداً لتنفيذ جزء من الكود البرمجي المطلوب على الأقل لاتمام الميزة.

المناقشات الغير رسمية بخصوص المشاكل، الميزات الجديدة، وتنفيذ الميزات الحالية يحدث في قناة #internals الموجودة في سيرفر لارافيل على ديسكورد. تايلور أوتويل، المشرف على لارافيل، عادة ما يكون متواجد على القناة في أيام الأسبوع من الساعة 8 صباحاً - وحتى الـ5 مساءً بتوقيت الولايات المتحدة الأمريكية (UTC-06:00 or America/Chicago)، ويكون حاضراً بشكل متقطع في القناة في أوقات أخرى.

أي فرع؟

جميع الإصلاحات يجب أن ترسل لاخر فرع (branch) مستقر. يجب ألا يتم ارسل الأخطاء التي تم اصلاحها للفرع الرئيسي master إلا في حال كان إصلاح لميزة موجودة فقط في إصدار قادم.

قد يتم إرسال الميزات الثانوية والمتوافقة تماماً مع الإصدارات السابقة للإصدار الحالي إلى أحدث فرع مستقر.

دائماً يجب إرسال الميزات الجديدة الرئيسية إلى الفرع الرئيسي master، الذي يحتوي على الإصدار القادم.

إذا لم تكن متأكداً بأن ميزتك مؤهلة لتكون ميزة رئيسية أو ميزة ثانوية، رجاءً قم بسؤال تايلور أوتويل في قناة #internals الموجودة في سيرفر لارافيل على ديسكورد.

الملفات المترجمة (Compiled Assets)

إذا كنت تقوم بتغيير يؤثر على ملف مترجم (compiled file)، مثل معظم الملفات الموجودة في resources/css أو resources/js في مستودع laravel/laravel، لا تقم بعمل (commit) للملفات المترجمة. لأنه ونظراً لحجمها الكبير، لايمكن مراجعتها بشكل واقعي وجيد من قبل المشرفين، حيث يمكن استغلال هذا الأمر لحقن كود ضار ضمن لارافيل. في إطار الحماية الدفاعية من هذه المشكلة، كل الملفات المترجمة سيتم إنشائها وعمل (commit) لها من قبل مشرفي لارافيل.

الثغرات الأمنية

اذا قمت باكتشاف ثغرة أمنية في لارافيل، رجاءً قم بإرسال بريد الكتروني لتايلور أوتويل على البريد التالي [email protected]. سيتم معالجة كل الثغرات الأمنية على الفور.

تنسيق الكود

تتبع لارافيل معيار التكويد PSR-2 ومعيار التحميل التلقائي PSR-4.

توثيق PHP

المثال في الأسفل يعبر عن كتلة توثيق لارافيل سليمة، لاحظ بأن الخاصية @param متبوعة بفراغين، من ثم نوع الوسيط، من ثم فراغين، واسم المتحول في النهاية:

/**
 * Register a binding with the container.
 *
 * @param  string|array  $abstract
 * @param  \Closure|string|null  $concrete
 * @param  bool  $shared
 * @return void
 *
 * @throws \Exception
 */
public function bind($abstract, $concrete = null, $shared = false)
{
    //
}

أداة StyleCI

لا تقلق اذا كان تنسيق الكود الخاص بك غير مثالي! أداة StyleCI تقوم اتوماتيكياً بإصلاح التنسيقات في مستودع لارافيل بعد دمج (merge) عملية سحب الطلب (pull requests). مما يمكننا من التركيز على محتوى المساهمة بدلاً من تنسيق الكود.

القواعد السلوكية

القواعد السلوكية الخاصة بلارافيل مشتقة من القواعد السلوكية الخاصة بروبي (Ruby). يمكن التبليغ عن أي انتهاكات للقواعد السلوكية لتايلور أوتويل ([email protected]):

• يجب على المساهمين أن يكونو متسامحين ويتقبلو وجهات النظر المخالفة.
• يجب على المساهمين التأكد من أن لغتهم وأفعالهم خالية من أي تهجم شخصي أو تعليقات شخصية مسيئة.
• يجب على المساهمين عند تفسير أقوال وأفعال الآخرين افتراض حسن النية دوماً.
• لن يتم التسامح مع أي سلوك يمكن اعتباره مضايقة.