إضافة الوثائق¶

قد يكون لديك أفضل برنامج في العالم - ولكن إذا لم يكن أحد يعرف كيفية استخدامه، فما الفائدة منه؟ يمكن دائمًا تحسين الوثائق - ونحن بحاجة إلى مساعدتك!

نماذج التوثيق¶

تمت كتابة وثائق BeeWare باستخدام MkDocs و Markdown. نهدف إلى اتباع إطار عمل Diataxis لتنظيم الوثائق.

يصف إطار عمل Diataxis أربعة "أشكال" من التوثيق:

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

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

على سبيل المثال، لنأخذ مهمة كتابة وثائق حول طريقة تحضير الكعك.

البرنامج التعليمي¶

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

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

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

دليل إرشادي¶

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

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

دليل الموضوعات¶

يصف دليل الموضوع موضوعًا أو فكرة واحدة. قد يتضمن أمثلة على أكواد أو تعليمات، ولكنه يركز بشكل أكبر على تقديم صورة عامة لمفهوم شامل. قد يتضمن آراء ووجهات نظر بديلة، ولكن يجب الحفاظ على التركيز على الموضوع المحدد للدليل.

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

مرجع¶

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

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

أسلوب التوثيق¶

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

الوثائق المساهمة¶

اقتراح وثائق جديدة

لديك فكرة حول تحسين BeeWare - كيف يمكنك تقديم هذه الفكرة للنظر فيها؟

قم ببحثك¶

الخطوة الأولى هي البحث في متتبع المشكلات BeeWare عن مشكلات الميزات (المشكلات التي تحمل علامة "تحسين"), مشكلات التوثيق (المشكلات التي تحمل علامة "توثيق"), أو مواضيع المناقشة لمعرفة ما إذا كانت الفكرة قد تم اقتراحها من قبل. إذا كان الأمر كذلك، وكان لديك سياق أو أفكار جديدة تود إضافتها، فقم بتضمينها في سلسلة المناقشة الحالية. إذا كنت ترغب في الحصول على مساعدة في بحثك، يمكنك أن تطلبها في قناة #dev على BeeWare Discord. قد نتمكن من توجيهك إلى سلاسل المناقشة الحالية، أو تزويدك بسياق قد لا تكون على دراية به، أو ربط فكرتك بفكرة أخرى قد لا تبدو ذات صلة في البداية.

ناقش الفكرة¶

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

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

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

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

هذا لا يعني أنها لم تكن فكرة جيدة! قد تكون هناك أسباب فنية تمنع تنفيذها. على سبيل المثال، قد نرفض فكرة ما إذا:

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

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

تحويل إلى طلب ميزة رسمي¶

بمجرد أن تصل المناقشة إلى توافق في الآراء حول شكل الميزة، يمكنك إنشاء [مشكلة طلب ميزة] جديدة (https://github.com/beeware/beeware/issues/new/choose) في متتبع المشكلات BeeWare، والتي تلخص المناقشة، مع ربطها بالمناقشة للحصول على السياق.

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

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

للمساهمة في BeeWare، يتعين عليك إعداد بيئة تطوير.

المتطلبات الأساسية¶

ستحتاج إلى تثبيت المتطلبات الأساسية التالية.

macOSLinuxWindows

BeeWare يتطلب Python 3.10+. ستحتاج أيضًا إلى طريقة لإدارة البيئات الافتراضية (مثل venv).

يمكنك التحقق من إصدار Python الذي قمت بتثبيته عن طريق تشغيل:

$ python3 --version

إذا كان لديك أكثر من إصدار واحد من Python مثبتًا، فقد تحتاج إلى استبدال python3 برقم إصدار محدد (على سبيل المثال، python3.13)

نوصي بتجنب الإصدارات الحديثة من Python (أي الإصدارات التي تحتوي على رقم إصدار فرعي ".0" أو ".1"، مثل 3.14.0). وذلك لأن الأدوات اللازمة لدعم Python على macOS غالبًا ما تكون متأخرة ولا تتوفر للإصدارات المستقرة الحديثة من Python.

BeeWare يتطلب Python 3.10+. ستحتاج أيضًا إلى طريقة لإدارة البيئات الافتراضية (مثل venv).

يمكنك التحقق من إصدار Python الذي قمت بتثبيته عن طريق تشغيل:

$ python3 --version

إذا كان لديك أكثر من إصدار واحد من Python مثبتًا، فقد تحتاج إلى استبدال python3 برقم إصدار محدد (على سبيل المثال، python3.13)

نوصي بتجنب الإصدارات الحديثة من Python (أي الإصدارات التي تحتوي على رقم إصدار فرعي ".0" أو ".1"، مثل 3.14.0). وذلك لأن الأدوات اللازمة لدعم Python على Linux غالبًا ما تكون متأخرة ولا تتوفر للإصدارات المستقرة الحديثة من Python.

BeeWare يتطلب Python 3.10+. ستحتاج أيضًا إلى طريقة لإدارة البيئات الافتراضية (مثل venv).

يمكنك التحقق من إصدار Python الذي قمت بتثبيته عن طريق تشغيل:

C:\...>py -3 --version

إذا كان لديك أكثر من إصدار واحد من Python مثبتًا، فقد تحتاج إلى استبدال -3 برقم إصدار محدد (على سبيل المثال، -python3.13)

نوصي بتجنب الإصدارات الحديثة من Python (أي الإصدارات التي تحتوي على رقم إصدار فرعي ".0" أو ".1"، مثل 3.14.0). وذلك لأن الأدوات اللازمة لدعم Python على Windows غالبًا ما تكون متأخرة ولا تتوفر للإصدارات المستقرة الحديثة من Python.

قم بإعداد بيئة التطوير الخاصة بك¶

الطريقة الموصى بها لإعداد بيئة التطوير لـ BeeWare هي استخدام بيئة افتراضية, ثم تثبيت إصدار التطوير لـ BeeWare وتبعياته.

نسخ مستودع BeeWare¶

بعد ذلك، انتقل إلى صفحة BeeWare على GitHub، وإذا لم تكن قد قمت بذلك بالفعل، فقم بفصل المستودع إلى حسابك الخاص. بعد ذلك، انقر على زر "<> Code" في النسخة المنقسمة. إذا كان تطبيق GitHub desktop مثبتًا على جهاز الكمبيوتر الخاص بك، فيمكنك تحديد "Open with GitHub Desktop"؛ وإلا، فانسخ عنوان URL HTTPS المقدم، واستخدمه لنسخ المستودع إلى جهاز الكمبيوتر الخاص بك باستخدام سطر الأوامر:

macOSLinuxWindows

قم بتقسيم مستودع BeeWare، ثم:

$ git clone https://github.com/<your username>/beeware.git

(استبدل اسم المستخدم الخاص بك على GitHub)

قم بتقسيم مستودع BeeWare، ثم:

$ git clone https://github.com/<your username>/beeware.git

(استبدل اسم المستخدم الخاص بك على GitHub)

قم بتقسيم مستودع BeeWare، ثم:

C:\...>git clone https://github.com/<your username>/beeware.git

(استبدل اسم المستخدم الخاص بك على GitHub)

إنشاء بيئة افتراضية¶

لإعداد بيئة افتراضية وترقية pip، قم بتشغيل:

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

يجب أن يكون أمام موجهك الآن بادئة (.venv).

تثبيت BeeWare¶

الآن بعد أن أصبح لديك شفرة المصدر، يمكنك إجراء تثبيت قابل للتحرير لـ BeeWare في بيئة التطوير الخاصة بك. قم بتشغيل الأمر التالي:

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

تمكين الالتزام المسبق¶

BeeWare يستخدم أداة تسمى pre-commit لتحديد المشكلات البسيطة وتوحيد تنسيق الكود. ويقوم بذلك عن طريق تثبيت git hook الذي يقوم تلقائيًا بتشغيل سلسلة من أدوات فحص الكود قبل إنهاء أي git commit. لتمكين pre-commit، قم بتشغيل:

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

الآن أنت جاهز لبدء الاختراق على BeeWare!

العمل من فرع

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

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

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

بدلاً من ذلك، يجب إجراء التغييرات على فرع الميزة. يتميز فرع الميزة باسم بسيط لتعريف التغيير الذي قمت بإجرائه. على سبيل المثال، إذا كنت تقوم بإصلاح خطأ يسبب مشكلات في البناء على Windows 11، فيمكنك إنشاء فرع ميزة fix-win11-build. إذا كان الخطأ يتعلق بمشكلة محددة تم الإبلاغ عنها، فمن الشائع أيضًا الإشارة إلى رقم المشكلة في اسم الفرع (على سبيل المثال، fix-1234).

لإنشاء فرع ميزة fix-win11-build، قم بتشغيل:

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build

تجنب توسع نطاق العمل

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

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

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

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

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

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

وثائق البناء

قبل إجراء أي تغييرات على وثائق BeeWare, من المفيد التأكد من أنه يمكنك إنشاء الوثائق الموجودة.

يجب أن يكون مترجم Python 3.13 مثبتًا ومتاحًا في مسارك (أي أن python3.13 يجب أن يبدأ مترجم Python 3.13).

BeeWare يستخدم tox لإنشاء الوثائق. يجب تشغيل أوامر tox التالية من نفس موقع ملف tox.ini، الموجود في الدليل الجذر للمشروع.

معاينة التوثيق المباشر¶

لدعم التحرير السريع للوثائق، يحتوي BeeWare على وضع "المعاينة المباشرة".

سيتم إنشاء المعاينة المباشرة مع ظهور تحذيرات!

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

يختلف "التحذير" عن "الخطأ". إذا أدخلت مشكلة تعتبر "خطأ"، فسوف يفشل الخادم المباشر، وسيتطلب إعادة التشغيل. ولن يعمل مرة أخرى حتى يتم حل مشكلة "التحذير".

لبدء تشغيل الخادم المباشر:

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

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

بمجرد بدء تشغيل الخادم، سترى شيئًا مثل ما يلي في إخراج وحدة التحكم:

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

افتح متصفحًا وانتقل إلى عنوان URL المقدم. الآن يمكنك البدء في تكرار الوثائق. إذا تم اكتشاف تغيير، فسيتم إعادة إنشاء الوثائق، وسيتم تحديث أي متصفح يعرض الصفحة المعدلة تلقائيًا.

docs-live هي خطوة أولية

يُقصد بتشغيل docs-live للعمل مع الخادم المباشر إجراء التكرار الأولي. يجب عليك دائمًا تشغيل بنية محلية قبل إرسال طلب سحب.

بناء محلي¶

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

إنشاء بنية محلية¶

لإنشاء بنية محلية:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

سيكون ناتج هذا البناء في دليل _build في جذر المشروع.

إنشاء نسخة مترجمة محلية¶

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

لإنشاء نسخة من جميع الترجمات المتاحة:

macOSLinuxWindows

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

سيكون ناتج كل بناء لغة في الدليل المرتبط _build/html/<languagecode>، حيث <languagecode> هو رمز اللغة المكون من حرفين أو خمسة أحرف المرتبط باللغة المحددة (على سبيل المثال fr للفرنسية، it للإيطالية، إلخ).

إذا وجدت مشكلة في بنية واحدة، يمكنك تشغيل تلك البنية بشكل منفصل عن طريق تشغيل tox -e docs-<languagecode>. على سبيل المثال، لتكوين الوثائق باللغة الفرنسية فقط، قم بتشغيل:

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

سيكون ناتج البناء أحادي اللغة في دليل _build.

توثيق linting¶

ستحدد عملية البناء مشاكل Markdown، ولكن BeeWare تقوم ببعض الفحوصات الإضافية للنمط والتنسيق، والمعروفة باسم "linting". لتشغيل فحوصات lint:

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

سيؤكد ذلك أن الوثائق لا تحتوي على:

روابط معطلة
الكلمات المكتوبة بشكل خاطئ

إذا تم تحديد تهجئة صحيحة لكلمة ما على أنها خاطئة، فقم بإضافة الكلمة إلى القائمة الموجودة في docs/spelling_wordlist. سيؤدي ذلك إلى إضافة الكلمة إلى قاموس المدقق الإملائي. عند الإضافة إلى هذه القائمة، تذكر ما يلي:

نفضل استخدام قواعد الإملاء الأمريكية، مع بعض الحرية في استخدام المصطلحات العامية الخاصة بالبرمجة (مثل "apps") وتحويل الأسماء إلى أفعال (مثل "scrollable").
يجب أن تستخدم أي إشارة إلى اسم منتج الأحرف الكبيرة المفضلة للمنتج. (على سبيل المثال، "macOS" و"GTK" و"pytest" و"Pygame" و"PyScript").
إذا كان المصطلح يستخدم "ككود"، فيجب اقتباسه حرفياً (مثل هذا) بدلاً من إضافته إلى القاموس.

كتابة الوثائق

هذه هي الخطوات التي يجب اتباعها لكتابة مساهمتك في الوثائق لـ BeeWare.

تحديث الوثائق الموجودة¶

إذا كنت تقوم بتحرير المستندات الموجودة، فستحتاج إلى تحديد موقع الملف في الدليل /docs/en. تتبع بنية الملف بنية الصفحة، لذا يمكنك تحديد موقع الملف باستخدام عنوان URL الخاص بالوثائق.

إضافة وثائق جديدة¶

إذا كنت تضيف مستندًا جديدًا، فهناك بعض الخطوات الإضافية التي يجب اتباعها.

ستحتاج إلى إنشاء المستند في الموقع المناسب داخل دليل docs/en. لغرض المناقشة، سنفترض أنك تضيف مستندًا جديدًا باسم الملف new_doc.md.

بعد ذلك، ستحتاج إلى تحديث ملف docs/en/SUMMARY.md لتضمين ملفك الجديد. يتم تنظيم ملف SUMMARY.md بحيث يعكس بشكل أساسي بنية دليل docs/en، ولكن الأهم من ذلك أنه يحدد بشكل مباشر بنية الشريط الجانبي الأيسر. إذا حددت المقطع الذي تريد تضمين new_doc.md فيه، فلن تحتاج إلى تغيير أي شيء في SUMMARY.md إذا رأيت مسارًا بديلًا مدرجًا. على سبيل المثال:

- ./path/to/directory/*

إذا كان القسم الذي تنوي تضمين new_doc.md فيه عبارة عن قائمة من روابط Markdown الفردية، فستحتاج إلى إضافة رابط صريح إلى رابطك. على سبيل المثال:

- [My new document](new_doc.md)

كتابة الوثائق الخاصة بك¶

يمكنك الآن فتح الملف المطلوب في محررك وبدء الكتابة.

لدينا دليل أسلوب التوثيق الذي يحدد إرشاداتنا لكتابة وثائق BeeWare.

إضافة ملاحظة تغيير

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

يجب أن يتضمن كل طلب سحب ملفًا واحدًا على الأقل في دليل changes/ يوفر وصفًا موجزًا للتغيير الذي تم تنفيذه بواسطة طلب السحب. يجب أن تكون ملاحظة التغيير بتنسيق Markdown، في ملف يحمل اسم التنسيق <id>.<fragment type>.md. إذا كان التغيير الذي تقترحه سيصلح خطأً أو ينفذ ميزة لها رقم مشكلة موجود، فسيكون المعرف هو رقم تلك التذكرة. إذا لم يكن للتغيير مشكلة مقابلة، فيمكن استخدام رقم PR كرقم تعريف. لن تعرف رقم PR هذا حتى تقوم بدفع طلب السحب، لذا ستفشل أول عملية CI في فحص towncrier؛ أضف ملاحظة التغيير وقم بدفع تحديث PR وستنجح عملية CI.

هناك خمسة أنواع من الأجزاء:

الميزة: يضيف PR سلوكًا أو إمكانية جديدة لم تكن ممكنة من قبل (على سبيل المثال، إضافة دعم لتنسيق تغليف جديد، أو ميزة جديدة في تنسيق تغليف موجود بالفعل)؛
bugfix: يعمل PR على إصلاح خطأ في التنفيذ الحالي؛
doc: تمثل العلاقات العامة تحسناً كبيراً في التوثيق؛
إزالة؛ يمثل PR تغييرًا غير متوافق مع الإصدارات السابقة في BeeWare API؛ أو
misc؛ تغيير بسيط أو إداري (مثل تصحيح خطأ مطبعي أو توضيح لغوي بسيط أو تحديث إصدار تابع) لا يحتاج إلى الإعلان عنه في ملاحظات الإصدار.

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

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

تطبيق فحص تعبير عادي أقوى لمنع أسماء المشاريع التي تبدأ بأرقام.

ستكون ملاحظة التغيير المقابلة كما يلي:

لم يعد من الممكن أن تبدأ أسماء المشاريع بأرقام.

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

123.feature.md
234.تصحيح الأخطاء.md
789.removal.1.md
789.removal.2.md

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

إرسال طلب سحب

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

العمل مع pre-commit¶

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

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

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

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

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

انقل التغييرات إلى GitHub وأنشئ طلب السحب الخاص بك¶

عندما تقوم بالدفع إلى GitHub لأول مرة، سيتم تزويدك بعنوان URL ينقلك مباشرة إلى صفحة GitHub لإنشاء طلب سحب جديد. اتبع عنوان URL وقم بإنشاء طلب السحب الخاص بك.

فيما يلي مثال على ما يمكن توقعه عند الضغط على "push"، مع تمييز عنوان URL.

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

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

انتقل إلى المستودع الأصلي، وانقر على "طلبات السحب" ثم "طلب سحب جديد"، واختر من أين تريد إرسال طلب السحب.
إذا قمت بالدفع مؤخرًا، فانتقل إلى المستودع الأصلي، وحدد الشعار الموجود أعلى قائمة الملفات الذي يشير إلى أن المستودع "تلقى دفعات مؤخرًا"، ثم انقر على الزر "مقارنة وطلب سحب".
استخدم أمر GitHub CLI gh pr create، واملأ المطالبات.
استخدم أمر GitHub CLI gh pr create --web لفتح متصفح الويب على صفحة إنشاء PR.

أي من هذه الخيارات سيمكنك من إنشاء طلب سحب جديد.

واجهة CLI GitHub: gh

يوفر GitHub GitHub CLI، الذي يتيح لك الوصول إلى العديد من ميزات GitHub من جهازك الطرفي، من خلال الأمر gh. تغطي وثائق GitHub CLI جميع الميزات.

سحب محتوى الطلب¶

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

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

إذا كانت هناك أي حالات إعادة إنتاج، أو أي نظام اختبار استخدمته ولم يتم تضمينه بالفعل في التغييرات الموجودة في PR، فيجب شرحها وإدراجها في PR. يجب أن يتضمن الشرح كيفية تشغيلها، وما يجب فعله لإعادة إنتاج النتيجة المرجوة.

إذا كان طلب السحب الخاص بك سيحل المشكلة رقم 1234، فيجب عليك تضمين النص "Fixes

1234" في وصف طلب السحب الخاص بك. سيؤدي ذلك إلى إغلاق المشكلة تلقائيًا عند دمج¶

طلب السحب. يمكنك الإشارة إلى مناقشات أو مشكلات أو طلبات سحب أخرى باستخدام نفس صيغة "#1234". يمكنك الإشارة إلى مشكلة في مستودع مختلف عن طريق إضافة علامة - قبل الرقم، على سبيل المثال، "python/cpython#1234" تشير إلى المشكلة 1234 في مستودع CPython.

التكامل المستمر¶

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

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

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

في بعض الأحيان، قد تفشل عملية فحص CI لأسباب لا علاقة لها بالتغييرات التي أجريتها. قد يكون ذلك بسبب مشكلة في الجهاز الذي يقوم بتشغيل فحص CI؛ أو لأن فحص CI غير مستقر. إذا لاحظت فشلًا، وكنت متأكدًا تمامًا أنه لا علاقة له بالتغييرات التي أجريتها، أضف تعليقًا إلى PR الخاص بك بهذا الشأن، وسنقوم بفحصه.

لبدء تشغيل CI جديد، تحتاج إلى دفع التغييرات الجديدة إلى فرعك.

إذا وجدت نفسك في موقف تحتاج فيه إلى المساعدة لتمرير CI، فاترك تعليقًا على PR لإعلامنا بذلك وسنبذل قصارى جهدنا لمساعدتك.

فحوصات pre-commit وtowncrier

إذا فشلت فحوصات pre-commit أو towncrier، فسيتم حظر تشغيل معظم فحوصات CI المتبقية. ستحتاج إلى حل المشكلات ذات الصلة قبل تشغيل مجموعة الفحوصات الكاملة.

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

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