Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
179 lines (112 sloc) 18.7 KB
id title layout permalink next redirect_from
how-to-contribute
دليل المساهمين
contributing
docs/how-to-contribute.html
codebase-overview.html
contributing/how-to-contribute.html
tips/introduction.html

تعتبر React من أوائل المشاريع المفتوحة المصدر من Facebook والتي ﻻزالت تحت التطوير المستمر والتي يتم استعمالها في شفرات برمجية للجميع في facebook.com. ﻻزلنا مستمرّين في العمل على إصلاح العلل لجعل المُساهمة في هذا المشروع أسهل وأكثر شفافية قدر الإمكان. لم نبلغ ذلك حقّا، لكن نتمنى أن يوضّح هذا المستند مراحل المساهمة ويجيب عن الأسئلة التي يمكن أن تُراودك.

القواعد السلوكيّة {#code-of-conduct}

قبل المشاركة، الرجاء منك أن تقرأ قواعدنا السلوكية، لقد تبنّينا ميثاق القواعد السلوكية للمساهمين ونتطلّع إلى أن يحترم أعضاء المجتمع قواعده.

التطوير المفتوح {#open-development}

كل العمل على React يحدث عل موقعGitHub. كل من الفريق الرئيسي والمساهمون الآخرون يساهمون بإرسال طلبات السحب (Pull requests) والتي تدخل نفس مراحل المراجعة.

تنظيم الفروع (Branch Organization) {#branch-organization}

نحرص على أن يكون الفرع الرئيسي (master branch) في أفضل حالة، بالاختبارات التي تمرّ بنجاح في كل مرّة. لكن حتى نتقدّم بسرعة، سنحدث تغييرات على الواجهة البرمجية (API) والتي ربما ستجعل تطبيقك غير متوافق معها. ننصحك باستعمال آخر اصدار مستقر من React.

من فضلك احرص على أن يكون طلب السحب (pull request) الذي تقوم به نحو الفرع الرئيسي master. نُبقي الفروع المستقرّة المختلفة للإصدارات الجذرية لكننا لن نقبل طلبات السحب نحوها مباشرة. بل ننتقي التغييرات التي ﻻ تُحدث تغييرات هدّامة من الفرع الرئيسي إلى آخر اصدار مستقر.

الإدارة الدلالية لنُسخ البرمجيات {#semantic-versioning}

تتبع React الإدارة الدلالية لنُسخ البرمجيات. نُصدر اصدارات ترقيع (patch versions) عند القيام بإصلاحات للعلل والثغرات، اصدارات صُغرى عند إضافة ميزات ووظائف جديدة، وإصدارات جذرية عند القيام بتغيرات جذرية. عند القيام بتغيير جذري نقوم باستخدام تحذيرات بعدم الصلاحية (deprecation warnings) في الإصدارات الصغرى حتى يعلم مستخدمونا بالتغيرات التي ستطرأ وحتى يرقّوا شفراتهم البرمجية مُسبقا.

كل طلب سحب يحمل وسمًا يحدد ما إذا كان سيذهب إلى الرُقعة (patch) أو إلى الإصدار الفرعي (minor) أو الإصدار الرئيسي (major). نُصدر نسخ الترقيع في كلّ أسبوع ونُصدر الإصدارات الصُغرى كل بضعة أشهر وأما الإصدارات الجذرية تكون مرّة أو مرّتين في السنة.

كل تغيير معتبر موثّق في جدول التغييرات (changelog).

العلل (Bugs) {#bugs}

أين تجد المشاكل المعروفة {#where-to-find-known-issues}

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

التبليغ عن مشكل جديد {#reporting-new-issues}

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

الثغرات الأمنية {#security-bugs}

لدى Facebook برنامج مكفآت للتبليغ الآمن عن الثغرات الأمنية. وبالتالي يرجى عدم التطرّق لذلك في العلن في (الـ issues). اذهب لتلك الصفحة واتبع الخطوات الموضحة هناك.

سُبُل التواصل {#how-to-get-in-touch}

هناك كذلك مجتمع نشيط من مستخدمي React على منصّة Discord للمحادثة إذا ما احتجت للمساعدة فيما يتعلّق بـReact.

اقتراح تغيير {#proposing-a-change}

إن أردت احداث تغيير بالواجهة البرمجية (API)، أو احداث أي تغييرات مُعتَبرة ننصحك بأن تقدم طلب مُشكلة (issue). هذا يُمكننا من مناقشة اقتراحك قبل أن تستثمر جهدك فيه.

إن كنت تُقدم على إصلاح مشكلة فحسب، ﻻ بأس بإرسال طلب سحب (pull request) مباشرة، لكن من المهم أن تقدم طلب مُشكلة (issue) تُحدّد فيها بالتفصيل ما أنت بصدد إصلاحه. هذا مُهم في حالة ما إذا كنّا ﻻ نقبل ذاك الإصلاح بالتحديد لكن يمكننا الاستمرار في العمل على تلك المُشكلة.

أول طلب سحب (Pull Request) لك {#your-first-pull-request}

هل تعمل على أول طلب سحب (Pull Request) لك؟ يمكنك أن تتعلّم كيفية عمل ذلك من سلسلة الفيديوهات المجانيّة التالية:

كيف تُساهم في مشروع مفتوح المصدر على Github

حتى نساعدك في تَبليل قَدَمَيْك (الإنطلاق لأوّل مرّة) وحتى تَعتاد على نظام المُساهمة الخاص بنا، لدينا قائمة ببعض المشاكل السهلة على المبتدئين (good first issues) والتي تحوي عِلَلا ذات نطاق محدود نسبيّا فتعتبَرُ مكانًا جيدا للإنطلاق منه.

إن قررت أن تُصلحَ مُشكلة (issue) قد تم طرحها، من فضلك ألقِ نظرة على النقاش في التعليقات لترى ما إذا كان أحدهم يعمل على إصلاحها. وإن لم يكن أي أحد يعمل عليها في ذلك الحين، الرجاء ترك تعليق بوضّح بأنك تريد العمل عليها حتى ﻻ يكرر الآخرون مَجهوداتك.

إن اقرّ أحدهم بأن هناك مشكلة ولم يعقّب على ذلك لأكثر من أسبوعين، ﻻ بأس أن تتناولها أنت لكن يجب عليك أن تَترُك تعليقًا على كلّ حال.

إرسال طلب سحب (Pull Request) {#sending-a-pull-request}

يراقب الفريق الرئيسي طلبات السحب (pull requests). سنقوم بمراجعة طلب السحب الخاص بك وبعدها يمكنن أن ندمجه أو نطلب من أن تُحدث تغييرات به، أو يمكن أن نغلقه مع شرح الأسباب. أما التغيّرات التي تمسّ الواجهة البرمجية (API) قد تتطلب منا إحداث تغييرات وإصلاحات في استخدماتنا الداخلية في Facebook.com، والتي قد تُسبب تأخرًا. سنبذل قصارى جهدنا في تقديم التحديثات والنتائج المحصلّة خلال العمليّة.

قبل تسجيل طلب السحب، الرجاء التحقق من إتمام ما يلي:

  1. قم باستنساخ المستودع المستودع (بعمل Fork) وبعدها أنشأ الفرع الخاص بك من الفرع الرئيسي master
  2. نفّذ الأمل yarn في مجلّد المستودع.
  3. إن أصلحت علّة أو أضفت شيفرة برمجية والتي تحتاج إلى اختبار، أضف الإختبارات.
  4. تأكّد من نجاح سلسلة الإختبارات (yarn test). نصيحة: yarn test --watch TestName مفيدة أثناء التطوير.
  5. نفّذ الأمر yarn test-prod للإختبار في وضع الإنتاج. الأمر يقبل نفس الخيارات (options) المتوفّرة مع الأمر yarn test.
  6. إن كنت تحتاج مُنقّحًا، نفّذ yarn debug-test --watch TestName، وافتح chrome://inspect، ثمّ اضغط على تفحّص(Inspect).
  7. نظّم شيفرتك البرمجية مع prettier بالأمر (yarn prettier).
  8. تأكّد من أن شيفرتك البرمجية متناسقة بالأمر (yarn lint). نصيحة: yarn linc للتحقق فقط من الملفّات المُتَغيّرة.
  9. نفّذ Flow للتحقق من الأصناف (typechecks) بالأمر (yarn flow).
  10. راجع اتفاقية ترخيص المساهم (CLA)، إن لم تقم بذلك بعد.

اتفاقية ترخيص المساهم (CLA) {#contributor-license-agreement-cla}

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

أكمل الـCLA الخاصّة بك من هنا

مُتطلّبات للمساهمة {#contribution-prerequisites}

  • لديك Node مثبّت بنسخته الـv8.0.0+ و Yarn بالنسخة v1.2.0+.
  • لديك gcc مُثبّت أو أنت مُعتاد على تثبيت المُتَرجمات (compilers) إذا ما احتجتها. بعض الإعتماديات (dependencies) تحتاج إلى مرحلة تَرجَمة (compilation step). في نظام OS X, طرفية Xcode (Xcode Command Line Tools) ستتكفّل بذلك، على Ubuntu، أمر apt-get install build-essential سيثبّت الحزم المطلوبة، أوامر مشابة يمكن أن تشتغل على توزعات لينُكس الأخرى. نظام ويندوز (Windows) سيتطلّب مراحل إضافية، راجع إرشادات تثبيت node-gyp لمزيد من التفاصيل.
  • أنت مُعتاد على Git.

آليّة التطوير {#development-workflow}

بعد استنساخ مشروع React على جهازك، نفّذ الأمر yarn لتحميل كل إعتماديّاته. بعدها يمكنك تنفيذ بعض الأوامر:

  • yarn lint للتحقق من تنسيق الشيفرة البرمجية.
  • yarn linc مثل yarn lint لكن أسرع ﻷنه يتحقق من الملفّات التي تغيّرت فحسب.
  • yarn test يشغّل كل سلسلة الإختبارات.
  • yarn test --watch يشغّل مُراقب الإختبارات التفاعلي (interactive tests watcher).
  • yarn test <نمط(pattern)> يشغلّ الإختبارات التي الموافقة لاسم الملف.
  • yarn test-prod تشغّل الإختبارات في بيئة الإنتاج، تقبل كل خيارات الأمر yarn test.
  • yarn debug-test يُشابه الأمر yarn test لكن مع مُنَقّح. افتح chrome://inspect ثمّ اضغط على تفحّص(Inspect).
  • yarn flow يشغّل آلية Flow للتحقق من الأصناف.
  • yarn build ينشأ مجلّد بناء (build) مع كل الحُزم.
  • yarn build react/index,react-dom/index --type=UMD ينشأ بنيات بناء (UMD) مُكوّنة من React و ReactDOM فقط.

ننصح باستعمال الأمر yarn test (أو ما يُشابهه من الأوامر أعلاه) للتأكد من عدم إتلاف أي شيء بينما تعمل على التغييرات التي تقوم بها. على كلّ، سيكون من الأحسن أن تختبر نسختك المبنيّة من React في مشروع حقيقي.

أولا، شغّل الأمر yarn build. هذا الأمر سينتج حزما مبنيّة مسبقا في مجلد build وستقوم تحضير حزم npm داخل build/packages.

أسهل طريقة لتجربة التغييرات التي قمت بها هي بتشغل الأمر yarn build react/index,react-dom/index --type=UMD ثم بفتح fixtures/packaging/babel-standalone/dev.html. هذا الملف أصلا يستعمل react.development.js من مجلّد build حتى يُتابع التغييرات التي تقوم بها.

إن قررت أن تجرّب تغييراتك على مشروع React مُنشأ مسبقا، يمكنك نسخ build/dist/react.development.js و build/dist/react-dom.development.js و أيّ من نواتج البناء (build products) ووضعها في تطبيقك ومن ثمّ استعمالها عِوضَ النسخة المستقرّة. إن كان مشروعك يستعمل React من npm، يمكنك حذف react و react-dom من مُعتمديّاته ثم استعمل yarn link لربطها مع مسار مجلّد build المحلّي لديك:

cd ~/مسار_نسختك_من_react/build/node_modules/react
yarn link
cd ~/مسار_نسختك_من_react/build/node_modules/react-dom
yarn link
cd /مسار/المشروع/project_مشروع
yarn link react react-dom

في كل مرّة تشغّل فيها الأمر yarn build في مجلّد React ستظهر النسخ المُحدّثة في مجلّد node_modules داخل مسار مشروعك. تستطيع عندها إعادة بناء مشروعك لتجربة التغييرات التي قُمت بها.

نؤكّد مجددا أن يتوفّر طلب السحب (pull request) الخاص بك على وحدات اختبار ﻷي ميزة جديدة. بذلك نضمن أننا لن نُعطّل شيفرتك البرمجية في المستقبل.

دليل التنسيق {#style-guide}

نستعمل مُنسّق شيفرات برمجية آلي يدعى Prettier. شغّل الأمر yarn prettier بعد القيام بأية تعديلات تمسّ الشيفرة البرمجية.

عندها ستقوم أداة التنسيق (linter) الخاصة بنا بالتقاط أغلب المشاكل التي يمكن أن توجد بشيفرتك البرمجية. يمكنك عبر الأمر yarn linc أن تتحقق من حالة تنسيق شيفرتك البرمجية.

يمكن لأداة التنسيق (linter) أن تفشل في التقاط بعض التنسيقات، إن كنت غير متأكد من شيء ما، راجع دليل تنسيق Airbnb سيقوم بإرشادك إلى الاتجاه الصحيح.

فيديو تمهيدي {#introductory-video}

قد تُهمّك مشاهدة هذا الفيديو القصير (26 دقيقة) والذي يمكن أن يُعطيك مقدمّة عن المساهمة في React.

أبرز أجزاء الفيديو: {#video-highlights}

  • 4:12 - بناء واختبار React محليّا
  • 6:07 - إنشاء وإرسال طلبات السحب (pull requests)
  • 8:25 - تنظيم الشيفرة البرمجية
  • 14:43 - تسجيل React بـnpm (React npm registry)
  • 19:15 - إضافة ميزات جديدة لـ React

لنيل نظرة واقعية عن "ما هو الشعور" عن القيام بالمساهمة في React للمرة الأولى، شاهد هذه المحاضرة الممتعة من ReactNYC.

طلب التعليقات (RFC أو Request for Comments) {#request-for-comments-rfc}

الكثير من التغييرات بما فيه إصلاحات العلل أو تحسين التوثيق تخضع لنظام طلبات السحب من Github (Github pull request workflow).

على الرغم من أن بعض التغييرات "ضرورية" ، فإننا نطلب أن يتم إدخالها قليلاً إلى عملية التصميم وإيجاد توافق في الآراء بين فريق React الأساسي.

يوفّر نظام "طلب التعليقات" (RFC أو Request for Comments) مسارا ثابتا ومؤطّرا للميزات الجديدة لتضاف للمشروع. يمكنك المساهمة بزيارة rfcs مستودع.

الرخصة {#license}

بمساهمتك في React، أنت توافق على أن مُساهماتك ستكون تحت رخصة MIT.

ماذا بعد؟ {#what-next}

إنتقل إلى القسم التالي للتعرف على تنسيق وتنظيم قاعدة الشيفرة البرمجية.

You can’t perform that action at this time.