نظرة عامة

يجب أن تكون جميع التغييرات على الكود والوثائق [مُرسلة] (/contributing/first-time/github/) عبر طلب سحب إلى مستودع GitHub للمشروع.

تحتوي معظم المشاريع على دليل مساهمة مخصص يحتوي على تفاصيل محددة لذلك المشروع، أو أنواع محددة من المساهمات. هذه الوثائق يمكن العثور عليها على اقرأ المستندات. على سبيل المثال، تحتوي [وثائق الوثائق] (https://briefcase.readthedocs.io) يحتوي على أدلة مساهمة أدلة لكل من الكود و وثائق.

يجب أن تلتزم جميع التقديمات المقدمة بـ [مدونة قواعد سلوك السلوك] (/community/behavior/code-of-conduct/).

تغيير الملاحظات

تتطلب العديد من مشاريع BeeWare، لا سيما مشروعي Briefcase و Toga، أن يتم إرسال كل طلب سحب مرفق بملاحظة تغيير. يتم تجميع ملاحظات التغيير هذه يتم تجميعها معًا عندما يتم قطع إصدار جديد للمشروع، مما ينتج عنه ملاحظات الإصدار للإصدار الجديد.

يستخدم برنامج BeeWare [برنامج بي وير] (https://towncrier.readthedocs.io/en/stable/) لـ إدارة ملاحظات التغيير.

يجب إنشاء ملف ملاحظة التغيير في دليل "التغييرات" وتسميته باستخدام التنسيق التالي وتسميته باستخدام هذا التنسيق:

<PR/إصدار رقم الإصدار>.<نوع التغيير>.rst

على سبيل المثال، طلب السحب الذي يعمل على إصلاح مشكلة GitHub #42 سيحمل اسم '42.bugfix.rst'. إذا لم يكن طلب السحب مرتبطًا بمشكلة معينة محدد، فيمكن استخدام رقم طلب السحب بدلاً من ذلك. قد تحتاج إلى إنشاء طلب السحب بدون ملاحظة تغيير للحصول على رقم طلب سحب المخصص، ثم دفع تحديث يتضمن ملاحظة التغيير مع برقم طلب السحب المخصص حديثًا.

يجب أن تكون أنواع التغيير لملاحظة التغيير أحد الأنواع التالية:

  • 'ميزة'
  • "إصلاح الأخطاء
  • 'وثيقة'
  • 'إزالة'
  • 'متفرقات'

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

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

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

تمت إضافة أداة التحقق من صحة تنسيق MM-DD-YYYYY إلى أداة التحقق من صحة التاريخ والقطعة سلسلة.

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

يمكن لأدوات التاريخ الآن قبول التواريخ بالصيغة الأمريكية.

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

نمط الرمز

تستخدم مشاريع BeeWare [ما قبل الالتزام] (https://pre-commit.com/) لأتمتة الالتزام بنمط التعليمات البرمجية. يتم تعريف هذه الفحوصات في ملف ملف '.pre-commit-config.yaml' لكل مستودع ويتم تشغيلها تلقائيًا في [CI] (/contributing/first-time/what-is-a/ci) عندما يتم فتح طلب سحب عند فتح طلب السحب.

لأتمتة عمليات التحقق من الالتزام المسبق في بيئة التطوير المحلية لديك مع كل التزام 'git'، قم بتشغيل 'التثبيت المسبق للالتزام'.

تشمل فحوصات ما قبل الالتزام المسبق:

  • [أسود] (https://black.readthedocs.io/en/stable/index.html) يضمن تنسيق رمز موحد
  • docformatter يضمن تنسيق موحد لسلاسل المستندات والتعليقات
  • يضمن pyupgrade استخدام الكود باستخدام أحدث الممارسات المثلى لبايثون
  • isort يضمن تنسيقًا موحدًا لعبارات 'الاستيراد' بيانات موحدة
  • flake8 يتحقق من وجود مشاكل شائعة في الترميز ومشاكل بناء الجملة الشائعة
  • عمليات التحقق من صحة المستندات المهيكلة مثل ملفات TOML و إزالة المسافات البيضاء غير الضرورية

إرشادات إضافية:

  • تجنب استخدام كلمة "نحن" في التعليقات، على سبيل المثال "نكرر" بدلاً من "نحن نكرر على"

  • استخدم الشرطات السفلية، وليس أحرف الجملة، للمتغيرات والدوال والطرق والدالة والطريقة

  • استخدم InitialCaps لأسماء الفئات (أو لدوال المصنع التي تُعيد فئات)

  • استخدم سلاسل المستندات على غرار سفنكس و '257'؛ شرح النوع مع '484' اختياري ولكن يُشجَّع عليه اختياري ولكن يُشجَّع عليه.

    على سبيل المثال:

    def function_name(param1: int، param2: str) -> bool:
    """"مثال على دالة ذات أنواع وسلسلة مستندات.

    :البارامتر بارام1: البارامتر الأول.
    :param param2: المعلمة الأولى: البارامتر الثاني.

    :المرتجعات: قيمة الإرجاع. صواب للنجاح، وخطأ خلاف ذلك.
    """

  • في سلاسل مستندات الاختبار، اذكر السلوك المتوقع أن يقوم كل اختبار يوضحه كل اختبار. لا تقم بتضمين ديباجات مثل "اختبار أن" أو "يضمن أن أن".

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

    def test_foo():
    """"تبدو سلسلة مستندات الاختبار هكذا (#123456).""""

  • ما لم ينص على خلاف ذلك، اتبع '8' (مع إيلاء اهتمام خاص لـ [القسم 2] (https://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds)).