3. عملية التطوير

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

3.1. مشروع قائم على git

ازداد تعقيد الشيفرة المصدرية لـ QGIS كثيرًا خلال السنوات الأخيرة. لذلك يصعب توقّع الآثار الجانبية التي ستنتج عن إضافة ميزة ما. في الماضي، كانت دورات إصدار مشروع QGIS طويلة جدًا لأن إعادة استقرار النظام البرمجي بعد إضافة ميزات جديدة كانت تتطلب جهدًا كبيرًا. وللتغلب على هذه المشكلات، انتقلت QGIS إلى نموذج تطوير يستخدم نظام التحكم في الإصدارات git: تُبرمَج الميزات الجديدة أولًا في فروع المساهمين، ثم تُدمج في فرع master الخاص بـ QGIS (الفرع الرئيسي) عندما تكتمل وتستقر.

الشيفرة المصدرية لـ QGIS مستضافة على https://github.com/qgis/QGIS.

3.1.1. الأدوار

توجد أدوار متعددة على GitHub. عندما يكون لديك حساب على GitHub فإنه يُسمح لك بالفعل بالمساهمة عبر إنشاء نسخة متفرعة (fork) من المستودع، ويكون دورك 'مساهم' (contributor). أما المطورون الأساسيون فهم 'متعاونون' (collaborators) ويمكنهم دمج الفروع في المستودع الأصلي (upstream) الرسمي.

3.1.2. البيئة

لتبدأ في استخدام مستودع QGIS والمساهمة فيه، تحتاج إلى:

1. امتلاك حساب على GitHub

2. إنشاء نسختك الخاصة من مستودع QGIS (انظر التفريع (fork))

3. امتلاك عميل git مثبّت على نظامك

4. إعداد بيئة git الخاصة بك

5. والاستمتاع!

3.1.3. تثبيت git

يوفر مشروع git إصدارات حديثة من البرنامج لمعظم المنصات. اتبع التعليمات على https://git-scm.com/downloads للحصول على النسخة المناسبة لنظام تشغيلك ومعماريته وتثبيتها. ومن هناك يمكن أيضًا تثبيت عميل git ذي واجهة رسومية لتصفح مستودعاتك وإدارتها (في معظم الأحيان سيثبّت git إن لم يكن متوفرًا بعد).

3.2. تطوير في الفروع

3.2.1. المساهمة في التطوير

بعد التسجيل في GitHub وإنشاء نسخة متفرعة من المستودع، يمكنك المشاركة كمساهم.

ملاحظة

يمكن المساهمة في شيفرة QGIS من مستودعك المتفرع على موقع GitHub. وستُبنى الشيفرة الجديدة تلقائيًا بواسطة بيئة الاختبار. لكن سرعان ما تظهر حدود سير العمل هذا عندما تريد تقديم تغييرات معقدة. وتفترض التعليمات أدناه وجود نسخة مستنسخة محلية.

يمكنك المساهمة عبر فتح طلب سحب (pull request). للقيام بذلك اتبع هذه الخطوات العامة:

1. استنسخ مستودعك على حاسوبك المحلي وأعدّ بيئة البناء

2. أنشئ فرعًا جديدًا وأجرِ التعديلات الخاصة بالتطوير

3. أودِع (commit) تغييراتك وادفع (push) فرعك إلى النسخة المتفرعة البعيدة على GitHub. وسيُعرض عليك بعدها مباشرة طلب سحب على شكل رابط ويب (URL).

4. افتح طلب سحب (PR) تطلب فيه سحب الإيداع (أو الإيداعات) من فرعك إلى الفرع master في المستودع الأصلي (upstream).

5. تبدأ عملية مراجعة تُعلم المساهمين والمتعاونين الآخرين بطلب السحب الخاص بك. وعليك التفاعل مع تعليقاتهم واقتراحاتهم.

ملاحظة

يتوفر شرح أكثر تفصيلًا لسير عمل التفريع والسحب (Fork & Pull) في Github على https://reflectoring.io/github-fork-and-pull/

ملاحظة

معظم مشاريع QGIS (الموقع الإلكتروني، التوثيق، واجهة pyQGIS البرمجية، الإضافات...) متاحة في صفحة المشروع على GitHub ويمكن المساهمة فيها باتباع العملية نفسها.

3.2.2. الوصول إلى مستودع

لكي تتمكن من التفاعل من قرصك المحلي مع كل من نسختك المتفرعة البعيدة ومستودعات QGIS الأصلية، تحتاج إلى:

1. إنشاء نسخة مستنسخة (clone) من نسختك على قرصك المحلي

   cd path/to/store/the/repository
   git clone https://github.com/<yourName>/QGIS.git
   

2. ربط مستودع QGIS الرئيسي (سنسميه upstream) بمستودعك

   git remote add upstream https://github.com/qgis/QGIS.git
   

3. التحقق من المستودعات البعيدة المرتبطة

   git remote -v
   # origin   https://github.com/<YourName>/QGIS.git (fetch)
   # origin   https://github.com/<YourName>/QGIS.git (push)
   # upstream https://github.com/qgis/QGIS.git (fetch)
   # upstream https://github.com/qgis/QGIS.git (push)
   

   أصبح مستودعك على الإنترنت متاحًا الآن من قرصك المحلي ويمكنك التفاعل معه باستخدام الاسم origin. وكلما أردت جلب التغييرات من مستودع qgis/QGIS، استخدم upstream.

ملاحظة

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

راجع الملف INSTALL في شجرة المصدر للحصول على تعليمات محددة لبناء إصدارات التطوير.

3.2.3. إجراء

1. الإعلان الأولي في القائمة البريدية أو مستودع البلاغات (issues):

   قبل البدء، أعلن في القائمة البريدية للمطورين لمعرفة ما إذا كان مطور آخر يعمل بالفعل على الميزة نفسها. ويمكنك أيضًا ذكر اهتمامك كتعليق في تقرير البلاغ إن وُجد في المستودع. وإذا كانت الميزة الجديدة تتطلب أي تغييرات في بنية QGIS، فيلزم تقديم مقترح تحسين QGIS (QEP).

2. أنشئ فرعًا في مستودعك المحلي:

   أنشئ فرع git جديدًا لتطوير الميزة الجديدة، استنادًا إلى أحدث حالة للفرع master.

   git fetch upstream master
   git checkout -b newfeature upstream/master
   

3. يمكنك الآن البدء بالتطوير:

   برمج تغييراتك على قرصك المحلي باستخدام بيئة التطوير المتكاملة (IDE) المعتادة لديك. وتذكّر كتابة مجموعة اختبارات لتعديلاتك عند الاقتضاء.

4. التنسيق السليم والتدقيق الإملائي وضبط جودة الشيفرة

   تتم إدارة التنسيق السليم والتدقيق الإملائي وضبط جودة الشيفرة عبر خطّاف git من نوع pre-commit.

   يمكن أتمتة ذلك بتشغيل:

   pre-commit install
   

   يمكن أيضًا تشغيل سكربت التدقيق الإملائي وحده باستخدام:

   ./scripts/astyle_all.sh
   

5. أودِع تغييراتك في مستودع git:

   عند إجراء إيداع، اكتب تعليقًا وصفيًا، ويُفضّل إجراء عدة إيداعات صغيرة إذا كانت التغييرات في عدد من الملفات غير مترابطة. وبالمقابل، نفضّل أن تجمع التغييرات المترابطة في إيداع واحد.

   git add path/to/your/files
   git commit -m "Add a comment describing your nice feature"
   

   بدون الخيار -m ستُفتح نافذة محرر جديدة لتكتب فيها رسالة الإيداع.

   إليك بعض التوصيات حول صيغة وصف الإيداع.

6. قد ترغب الآن في مشاركة عملك مع أعضاء مجتمع QGIS. ادفع ميزتك الجديدة إلى مستودعك المتفرع على الإنترنت بتنفيذ:

   git push origin newfeature
   

   ملاحظة

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

7. قدّم تغييراتك عبر طلب سحب

   بفتح طلب السحب تنطلق مجموعة الاختبارات المؤتمتة وتتحقق مما إذا كانت تغييراتك تتبع إرشادات كتابة الشيفرة في QGIS ولا تعطّل أي ميزة قائمة. وسيلزمك إصلاح أي مشكلات مُبلَّغ عنها قبل دمج فرعك في المستودع الأصلي.

   نصيحة

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

8. أعِد التأسيس (rebase) على الفرع master الأصلي بانتظام:

   يوصى بإعادة التأسيس (rebase) بانتظام لدمج تغييرات master في الفرع. فهذا يسهّل دمج الفرع في master لاحقًا. وبعد إعادة التأسيس تحتاج إلى تنفيذ git push -f إلى مستودعك المتفرع.

   git pull --rebase upstream master
   git push -f origin newfeature
   

ملاحظة

انظر المواقع التالية للحصول على معلومات حول أن تصبح رائدًا في GIT.

• https://git-scm.com/book/en/v2

• https://gitready.com

• https://support.github.com/

3.2.4. الاختبار قبل الدمج في master

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

3.3. تقديم طلبات السحب

هناك بعض الإرشادات التي ستساعدك على إدخال رقعك (patches) وطلبات السحب الخاصة بك إلى QGIS بسهولة، وتساعدنا على التعامل مع الرقع المرسلة إلينا بسهولة.

بشكل عام، يكون الأمر أسهل على المطورين إذا قدّمت طلبات سحب عبر GitHub. لن نشرح طلبات السحب هنا، بل نحيلك إلى توثيق طلبات السحب في GitHub.

إذا قدّمت طلب سحب فنرجو منك دمج master في فرع طلب السحب بانتظام بحيث يكون طلبك دائمًا قابلًا للدمج في الفرع master الأصلي.

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

إذا كنت مطورًا وترغب في تقييم قائمة طلبات السحب المنتظرة، فهناك أداة رائعة تتيح لك ذلك من سطر الأوامر

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

• ساعد في مراجعة طلبات سحب الآخرين لتفريغ الشخص المكلَّف بطلبك.

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

• أرسل رسالة إلى الشخص المكلَّف بطلبك في قائمة طلبات السحب.

• أرسل رسالة إلى اللجنة التوجيهية للمشروع تطلب فيها المساعدة في دمج طلبك في الشيفرة المصدرية.

3.3.1. أفضل الممارسات لإنشاء طلب سحب

• ابدأ دائمًا فرع الميزة من الحالة الحالية للفرع master.

• إذا كنت تبرمج فرع ميزة، فلا تقم بعملية "merge" لأي شيء في ذلك الفرع، بل أعِد التأسيس (rebase) كما هو موضح في النقطة التالية للحفاظ على سجلك نظيفًا.

• قبل إنشاء طلب سحب نفّذ git fetch upstream و git rebase upstream/master (على افتراض أن upstream هو المستودع البعيد للمستخدم qgis وليس مستودعك البعيد الخاص، تحقق من .git/config أو نفّذ git remote -v | grep github.com/qgis).

• يمكنك تنفيذ git rebase كما في السطر الأخير مرارًا دون إحداث أي ضرر (طالما أن الغرض الوحيد من فرعك هو دمجه في master).

• انتبه: بعد إعادة التأسيس تحتاج إلى تنفيذ git push -f إلى مستودعك المتفرع. أيها المطورون الأساسيون: لا تفعلوا هذا على مستودع QGIS العام!

3.3.2. وسوم خاصة لتنبيه كتّاب التوثيق

يوجد وسم خاص (Needs Documentation) يمكن للمراجعين إسناده إلى طلب السحب الخاص بك لتوليد تقارير بلاغات تلقائيًا في مستودع QGIS-Documentation بمجرد دمج طلبك. تذكّر أن تذكر ما إذا كانت ميزتك تستحق هذا الوسم.

علاوة على ذلك، يمكنك إضافة علامات خاصة إلى رسائل الإيداع لتقديم مزيد من المعلومات لكتّاب التوثيق. وتُضاف رسالة الإيداع حينها إلى تقرير البلاغ المولَّد:

• [needs-docs] لتوجيه كتّاب التوثيق إلى إضافة بعض التوثيق الإضافي بعد إصلاح وظيفة موجودة أصلًا أو الإضافة إليها.

• [feature] في حالة الوظائف الجديدة. وسيكون كتابة وصف جيد في طلب السحب بداية جيدة.

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

3.3.3. العناية الواجبة

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

3.4. معايير دمج طلبات السحب

يُرجى الاطلاع على QEP 323 - سياسات تقديم التغييرات ودمجها لمعرفة السياسات الحالية المتعلقة بتقديم طلبات السحب المقبولة.

3.5. الحصول على صلاحية الكتابة في GIT

صلاحية الكتابة في شجرة المصدر لـ QGIS تُمنح بالدعوة. عادةً عندما يقدّم شخص عدة رقع جوهرية (لا يوجد عدد محدد هنا) تُظهر كفاءة أساسية وفهمًا للغة C++ ولأعراف كتابة الشيفرة في QGIS، يمكن لأحد أعضاء اللجنة التوجيهية للمشروع (PSC) أو غيرهم من المطورين الحاليين ترشيح ذلك الشخص لدى اللجنة لمنحه صلاحية الكتابة. ويجب على المرشِّح تقديم فقرة تعريفية أساسية توضح سبب اعتقاده بأن ذلك الشخص يستحق صلاحية الكتابة. وفي بعض الحالات نمنح صلاحية الكتابة لغير مطوري C++ مثل المترجمين وكتّاب التوثيق. وفي هذه الحالات يجب أن يكون الشخص قد أظهر قدرته على تقديم الرقع، ويُفضّل أن يكون قد قدّم عدة رقع جوهرية تُظهر فهمه لكيفية تعديل الشيفرة المصدرية دون إفساد شيء، وما إلى ذلك.

ملاحظة

منذ الانتقال إلى GIT، أصبحنا أقل ميلًا لمنح صلاحية الكتابة للمطورين الجدد لأن مشاركة الشيفرة في github أمر بسيط عبر تفريع QGIS ثم تقديم طلبات سحب.

تحقق دائمًا من أن كل شيء يُترجَم (compile) بنجاح قبل إجراء أي إيداعات أو طلبات سحب. وحاول أن تكون على دراية بالأعطال المحتملة التي قد تسببها إيداعاتك لمن يبنون على منصات أخرى وبإصدارات أقدم أو أحدث من المكتبات.