Contributions Welcome!

نرحب بمساهماتكم في Hyperledger بأشكال عديدة، وهناك دائمًا الكثير للقيام به!

قبل أي شيء، نرجو مراجعة مدونة قواعد السلوك في مشروع Hyperledger قبل المشاركة. من المهم أن نحافظ على بيئة مهذبة للجميع.

Note

إذا كنت ترغب في المساهمة في هذا التوثيق، يرجى مراجعة Style guide for contributors.

Ways to contribute

هناك العديد من الطرق التي يمكنك من خلالها المساهمة في Hyperledger Fabric، سواء كمستخدم عادي أو كمطوّر.

كمستخدم:

ككاتب أو مطور معلومات:

  • قم بتحديث التوثيق باستخدام خبرتك مع Fabric وهذا التوثيق لتحسين المواضيع الحالية وإنشاء مواضيع جديدة. يعتبر إجراء تغيير على التوثيق طريقة سهلة للبدء كمساهم، كما أنه يسهل على المستخدمين الآخرين فهم واستخدام Fabric، ويزيد من سجل الـ commits المفتوحة المصدر الخاصة بك.
  • شارك في ترجمة اللغة للحفاظ على توثيق Fabric محدثًا بلغتك المفضلة. يتوفر توثيق Fabric بعدة لغات - الإنجليزية، الصينية، المالايالامية، والبرتغالية البرازيلية - فلماذا لا تنضم إلى فريق يحافظ على تحديث التوثيق المفضل لديك؟ ستجد مجتمعًا ودودًا من المستخدمين والكتاب والمطورين للتعاون معهم.
  • ابدأ ترجمة جديدة إذا لم يكن توثيق Fabric متاحًا بلغتك. لقد بدأت فرق الترجمة الصينية والمالايالامية والبرتغالية البرازيلية بهذه الطريقة، وأنت أيضًا تستطيع! العمل سيكون أكثر، حيث ستحتاج إلى تكوين مجتمع من الكتاب وتنظيم المساهمات؛ لكنه حقًا شعور رائع أن ترى توثيق Fabric متاحًا بلغتك المفضلة.

انتقل إلى `المساهمة في التوثيق`_ لبدء رحلتك.

كمطور:

Getting a Linux Foundation account

للمشاركة في تطوير مشروع Hyperledger Fabric، سوف تحتاج إلى حساب في Linux Foundation. بمجرد حصولك على LF ID، ستتمكن من الوصول إلى جميع أدوات مجتمع Hyperledger، بما في ذلك إدارة المشكلات في Jira، RocketChat، و الويكي (للتحرير فقط).

اتبع الخطوات التالية لإنشاء حساب Linux Foundation إذا لم يكن لديك واحد بالفعل:

  1. انتقل إلى موقع هوية Linux Foundation.
  2. اختر الخيار I need to create a Linux Foundation ID، وقم بتعبئة النموذج الذي سيظهر.
  3. انتظر بضع دقائق، ثم ابحث عن رسالة بريد إلكتروني بعنوان: "Validate your Linux Foundation ID email".
  4. افتح الرابط الوارد في البريد الإلكتروني للتحقق من عنوان بريدك الإلكتروني.
  5. تأكد من ظهور الرسالة التالية في متصفحك: You have successfully validated your e-mail address.
  6. يمكنك الآن الوصول إلى إدارة المشكلات في Jira، أو RocketChat.

Contributing documentation

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

Project Governance

يتم إدارة Hyperledger Fabric بموجب نموذج حوكمة مفتوحة كما هو موضح في ميثاقنا. يتم قيادة المشاريع والمشاريع الفرعية من قبل مجموعة من الحافظين (maintainers). يمكن للمشاريع الفرعية الجديدة تعيين مجموعة أولية من الحافظين الذين سيتم اعتمادهم من قبل حافظي المشروع الرئيسي الحاليين عند الموافقة على المشروع لأول مرة.

Maintainers

يتم قيادة مشروع Fabric من قبل الحافظين على مستوى المشروع. الحافظون مسؤولون عن مراجعة ودمج جميع التصحيحات المقدمة للمراجعة، وهم يوجهون الاتجاه التقني العام للمشروع ضمن المبادئ التوجيهية التي تحددها لجنة التوجيه الفني في Hyperledger (TSC).

Becoming a maintainer

سيقوم حافظو المشروع من وقت لآخر بالنظر في إضافة حافظ جديد، بناءً على المعايير التالية:

  • سجل مثبت من مراجعات طلبات السحب (جودة وكمية المراجعات)
  • قيادة فكرية مثبتة في المشروع
  • إثبات القدرة على إرشاد عمل المشروع والمساهمين

يمكن لحافظ حالي تقديم طلب سحب (pull request) لتحديث ملف الحافظين. يمكن أن يصبح المساهم المعين حافظًا بموافقة الأغلبية من قبل الحافظين الحاليين. بمجرد الموافقة، يتم دمج مجموعة التغييرات ويتم إضافة الفرد إلى مجموعة الحافظين.

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

Releases

يوفر Fabric إصدارًا جديدًا كل أربعة أشهر تقريبًا يتضمن ميزات وتحسينات جديدة. يتم دمج عمل الميزات الجديدة في الفرع الرئيسي (master) لـ Fabric على Github. يتم إنشاء فروع الإصدارات قبل كل إصدار حتى يتمكن الكود من الاستقرار بينما تستمر الميزات الجديدة في الاندماج مع الفرع الرئيسي. سيتم أيضًا إعادة إرسال الإصلاحات المهمة إلى أحدث فرع إصدار LTS (الدعم طويل الأمد)، وإلى فرع إصدار LTS السابق خلال فترات تداخل إصدارات LTS.

راجع الإصدارات لمزيد من التفاصيل.

Making Feature/Enhancement Proposals

يمكن تنفيذ التحسينات الطفيفة ومراجعتها من خلال سير عمل GitHub pull request المعتاد ولكن بالنسبة للتغييرات الأكبر، يتبع Fabric عملية RFC (طلب تعليقات).

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

لاقتراح ميزة جديدة، تحقق أولاً من JIRA و`مستودع RFC الخاص بـ Fabric <https://github.com/hyperledger/fabric-rfcs/>`__ للتأكد من عدم وجود اقتراح مفتوح (أو مغلق مؤخرًا) لنفس الوظيفة. إذا لم يكن هناك اقتراح، فاتبع عملية RFC لتقديم الاقتراح.

Contributor meeting

يعقد الحافظون اجتماعات منتظمة للمساهمين. الغرض من اجتماعات المساهمين هو التخطيط ومراجعة تقدم الإصدارات والمساهمات، ومناقشة الاتجاهات التقنية والتشغيلية للمشروع والمشاريع الفرعية.

يرجى الاطلاع على الويكي للحصول على تفاصيل اجتماعات الحافظين.

يجب تقديم مقترحات الميزات والتحسينات الجديدة كما هو موضح أعلاه إلى اجتماع الحافظين للنظر فيها وإبداء الملاحظات والقبول.

Release roadmap

يتم الاحتفاظ بخارطة طريق إصدار epics الخاصة بـ Fabric في JIRA.

Communications

نستخدم RocketChat للتواصل و Google Hangouts™ لمشاركة الشاشة بين المطورين. يتم التخطيط للتطوير ووضع الأولويات في JIRA، ونقوم بالمشاريع طويلة الأجل discussions/decisions to the mailing list.

Contribution guide

Install prerequisites

قبل أن نبدأ، إذا لم تقم بذلك بالفعل، فقد ترغب في التحقق من أن لديك كل المتطلبات الأساسية المثبتة على المنصة (المنصات) التي ستعمل عليها لتطوير تطبيقات blockchain و/أو تشغيل Hyperledger Fabric.

Getting help

إذا كنت تبحث عن شيء ما للعمل عليه، أو تحتاج إلى مساعدة خبير في تصحيح الأخطاء أو إيجاد حل لمشكلة ما، فإن مجتمعنا دائماً على استعداد للمساعدة. يمكنك التواصل معنا على الدردشة، أو IRC (#hyperledger على freenode.net) أو قوائم البريد الإلكتروني. معظمنا ودودون :grin: وسيسعدون بمساعدتك. السؤال الوحيد الغبي هو الذي لا تطرحه. في الواقع، تعتبر الأسئلة طريقة رائعة للمساعدة في تحسين المشروع لأنها تسلط الضوء على الأماكن التي يمكن أن تكون وثائقنا أكثر وضوحاً.

Reporting bugs

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

Note

إذا كان العيب متعلقًا بالأمان، يرجى اتباع عملية الإبلاغ عن أخطاء الأمان في Hyperledger عملية الإبلاغ عن أخطاء الأمان.

إذا لم يتم الإبلاغ عن المشكلة مسبقًا، يمكنك إما إرسال PR مع رسالة commit موثقة جيدًا تصف العيب والإصلاح، أو يمكنك إنشاء تقرير JIRA جديد. يرجى تقديم معلومات كافية للسماح لشخص آخر بإعادة إنتاج المشكلة. يجب أن يرد أحد حافظي المشروع على مشكلتك خلال 24 ساعة. إذا لم يحدث ذلك، يرجى متابعة المشكلة بإضافة تعليق وطلب مراجعتها. يمكنك أيضًا النشر في قناة Hyperledger Fabric ذات الصلة على دردشة Hyperledger. على سبيل المثال، يجب بث خطأ في التوثيق إلى #fabric-documentation، وخطأ في قاعدة البيانات إلى #fabric-ledger، وهكذا...

Submitting your fix

إذا قمت للتو بإرسال تقرير JIRA عن خطأ اكتشفته، وترغب في تقديم إصلاح له، فنحن نرحب بذلك بكل سرور! يرجى تعيين مشكلة JIRA لنفسك، ثم تقديم طلب سحب (PR). يرجى الرجوع إلى GitHub Contributions للحصول على سير عمل مفصل.

Fixing issues and working stories

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

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

Reviewing submitted Pull Requests (PRs)

هناك طريقة أخرى للمساعدة والتعرف على Hyperledger Fabric وهي مساعدة الحافظين في مراجعة طلبات السحب (PRs) المفتوحة. في الواقع، يتعين على الحافظين مراجعة جميع طلبات السحب المقدمة وتقييم ما إذا كان يجب دمجها أم لا. يمكنك مراجعة تغييرات الكود و/أو التوثيق، واختبار التغييرات، وإخبار المقدمين والحافظين برأيك. بمجرد اكتمال مراجعتك و/أو اختبارك، ما عليك سوى الرد على طلب السحب بنتائجك، عن طريق إضافة تعليقات و/أو التصويت. تعليق يقول شيئًا مثل "لقد جربته على النظام X وهو يعمل" أو ربما "واجهت خطأً على النظام X: xxx" سيساعد الحافظين في تقييمهم. ونتيجة لذلك، سيتمكن الحافظون من معالجة طلبات السحب بشكل أسرع وسيستفيد الجميع من ذلك.

ما عليك سوى تصفح طلبات السحب المفتوحة على GitHub للبدء.

PR Aging

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

PR Aging Policy

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

إذا تم اجتياز طلب سحب مقدم لجميع عمليات التحقق ولكن لم تتم مراجعته خلال 72 ساعة (3 أيام)، فسيتم إرسال إشعار إلى قناة #fabric-pr-review يوميًا حتى يتلقى تعليق مراجعة واحد على الأقل.

تنطبق هذه السياسة على جميع مشاريع Fabric الرسمية (fabric, fabric-ca, fabric-samples, fabric-test, fabric-sdk-node, fabric-sdk-java, fabric-sdk-go, fabric-gateway-java, fabric-chaincode-node, fabric-chaincode-java, fabric-chaincode-evm, fabric-baseimage, و fabric-amcl).

Setting up development environment

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

What makes a good pull request?

  • تغيير واحد في كل مرة. ليس خمسة، ولا ثلاثة، ولا عشرة. واحد فقط. لماذا؟ لأن هذا يحد من نطاق التغيير. إذا كان لدينا تراجع، فسيكون من الأسهل بكثير تحديد الـ commit المسبب بدلاً من وجود تغيير مركب يؤثر على المزيد من الكود.
  • إذا كانت هناك مشكلة Jira أو خطأ مقابلة، فقم بتضمين رابط لمشكلة Jira في ملخص PR ورسالة الـ commit. لماذا؟ لأن الحافظ الذي سيقوم بدمج PR سيحتاج إلى إغلاق أي مشكلة Jira مقابلة. أيضًا، في كثير من الحالات، سيكون هناك مناقشة إضافية حول تغيير مقترح أو خطأ في Jira.
  • قم بتضمين اختبارات الوحدة والتكامل (أو التغييرات على الاختبارات الموجودة) مع كل تغيير. وهذا لا يعني مجرد اختبار المسار السعيد فقط. بل يعني أيضًا اختبارًا سلبيًا لأي كود دفاعي يتعامل مع الأخطاء بشكل صحيح. عندما تكتب كودًا، فأنت مسؤول عن اختباره وتقديم الاختبارات التي تثبت أن التغيير الخاص بك يفعل ما يدعيه. لماذا؟ لأنه بدون هذا لن يكون لدينا أي فكرة عما إذا كان الكود الحالي يعمل بالفعل أم لا.
  • لا ينبغي أن تحتوي اختبارات الوحدة على تبعيات خارجية. يجب أن تكون قادرًا على تشغيل اختبارات الوحدة مباشرة باستخدام go test أو ما يعادله للغة المستخدمة. أي اختبار يتطلب بعض التبعيات الخارجية (على سبيل المثال يحتاج إلى سكريبت لتشغيل مكون آخر) يحتاج إلى محاكاة مناسبة. أي شيء آخر ليس اختبار وحدة، بل هو اختبار تكامل بحكم التعريف. لماذا؟ لأن العديد من مطوري المصادر المفتوحة يتبعون منهجية تطوير قائم على الاختبار (TDD). حيث يقومون بوضع مراقبة على المجلد الذي يستدعي الاختبارات تلقائيًا عند تغيير الكود. هذا أكثر كفاءة بكثير من الحاجة إلى تشغيل بناء كامل بين التغييرات. انظر إلى هذا التعريف لاختبار الوحدة للحصول على مجموعة جيدة من المعايير التي يجب مراعاتها عند كتابة اختبارات وحدة فعالة.
  • قلل عدد أسطر الكود لكل PR. لماذا؟ لأن الحافظين لديهم وظائف يومية أيضًا. إذا أرسلت تغييرًا بحجم 1000 أو 2000 سطر من الكود، فكم من الوقت تعتقد أن الأمر سيستغرق لمراجعة كل هذا الكود؟ حافظ على تغييراتك أقل من 200-300 سطر من الكود، إذا أمكن. إذا كان لديك تغيير أكبر، فقم بتقسيمه إلى تغييرات مستقلة متعددة. إذا كنت تضيف مجموعة من الوظائف الجديدة لتحقيق متطلبات قدرة جديدة، أضفها بشكل منفصل مع اختباراتها، ثم اكتب الكود الذي يستخدمها لتقديم الوظيفة المطلوبة. بالطبع، هناك دائمًا استثناءات. إذا أضفت تغييرًا صغيرًا ثم أضفت 300 سطر من الاختبارات، فسيتم مسامحتك ;-) إذا كنت بحاجة إلى إجراء تغيير له تأثير واسع أو يتعلق بمجموعة من الكود المُنشأ (مثل protobufs، إلخ). مرة أخرى، يمكن أن تكون هناك استثناءات.

Note

من المرجح ألا يتم الموافقة على طلبات السحب الكبيرة، مثل تلك التي تحتوي على أكثر من 300 سطر من الكود، وسيُطلب منك إعادة هيكلة التغيير ليتوافق مع هذه الإرشادات.

  • اكتب رسالة commit ذات معنى. قم بتضمين عنوان ذي معنى لا يتجاوز 55 حرفًا، يتبعه سطر فارغ، ثم وصف أكثر شمولاً للتغيير.

Note

Example commit message:

[FAB-1234] fix foobar() panic

Fix [FAB-1234] added a check to ensure that when foobar(foo string)
is called, that there is a non-empty string argument.

أخيرًا، كن مستجيبًا. لا تدع طلب السحب يتراكم عليه تعليقات المراجعة إلى الحد الذي يتطلب إعادة تنظيم (rebase). هذا لن يؤدي إلا إلى مزيد من التأخير في دمجه وإضافة المزيد من العمل عليك - لحل تعارضات الدمج.