1. مساهمة خطوة بخطوة

ملاحظة

مع أن QGIS-Documentation يُستخدم لشرح العملية، فإن جميع الأوامر والخطوات الموضحة أدناه تنطبق أيضًا على QGIS-Website.

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

لأي مساعدة، لا تتردد في السؤال في تعليق على تقرير المشكلة الذي تحاول إصلاحه أو في الكتابة إلى قائمة QGIS-community-team. واقرأ المعلومات العامة حول دعم مجتمع QGIS.

لنتعمق الآن في العملية.

تُخزَّن مصادر التوثيق باستخدام نظام التحكم في الإصدارات Git وهي متاحة على GitHub في https://github.com/qgis/QGIS-Documentation. ويمكن العثور على قائمة بالمشكلات المطلوب إصلاحها والميزات المطلوب شرحها في https://github.com/qgis/QGIS-Documentation/issues.

نصيحة

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

هناك طريقتان رئيسيتان، غير متعارضتين، لتعديل الملفات:

  1. استخدام واجهة الويب في GitHub

  2. استخدام أدوات سطر الأوامر في Git.

1.1. استخدام واجهة الويب في GitHub

تتيح لك واجهة الويب في GitHub القيام بما يلي:

  • تحرير الملفات

  • معاينة تغييراتك وإيداعها (commit)

  • إنشاء طلب سحب (pull request) لإدراج تغييراتك في المستودع الرئيسي

  • إنشاء الفروع أو تحديثها أو حذفها

إذا لم تكن معتادًا بعد على مصطلحات Git و GitHub، فقد ترغب في قراءة مشروع Hello-world في GitHub لتتعلم بعض المصطلحات والإجراءات الأساسية التي ستُستخدم أدناه.

ملاحظة

إذا كنت تصلح مشكلة مُبلَّغًا عنها

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

1.1.1. اشتقاق (Fork) مستودع QGIS-Documentation

بافتراض أن لديك بالفعل حسابًا على GitHub، عليك أولًا اشتقاق (fork) الملفات المصدرية للتوثيق.

انتقل إلى صفحة مستودع QGIS-Documentation وانقر على الزر githubFork في الزاوية العلوية اليمنى.

ستجد في حسابك على GitHub مستودع QGIS-Documentation (https://github.com/<YourName>/QGIS-Documentation). هذا المستودع نسخة من مستودع QGIS-Documentation الرسمي، ولديك فيه صلاحية كتابة كاملة ويمكنك إجراء تغييرات دون التأثير في التوثيق الرسمي.

1.1.2. إجراء التغييرات

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

البديل 1: استخدام الاختصار Edit on GitHub

يمكن تحرير صفحات موقع توثيق QGIS بسرعة وسهولة بالنقر على الرابط Edit on GitHub:

  • أعلى يمين كل صفحة،

  • أو في القائمة المنسدلة أسفل الشريط الجانبي الأيسر.

  1. سيفتح ذلك الملف في الفرع qgis:master مع رسالة أعلى الصفحة تخبرك بأنه ليس لديك صلاحية كتابة على هذا المستودع وأن تغييراتك ستُطبَّق على فرع جديد في مستودعك.

    ملاحظة

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

  2. أجرِ تغييراتك. وبما أن التوثيق مكتوب بصياغة reStructureText، فقد تحتاج بحسب تغييراتك إلى الاستعانة بإرشادات الكتابة.

  3. بعد الانتهاء من تعديل الملف، اضغط على Commit changes... وأضف عنوانًا قصيرًا يشرح تغييراتك. ويمكنك أيضًا تقديم شرح أكثر تفصيلًا إن لزم الأمر.

  4. اضغط على Propose changes لحفظ التعديلات في مستودعك. سيؤدي ذلك إلى إنشاء فرع مخصص (patch-xxx) في مستودعك، وسيفتح متصفح الويب الصفحة Comparing changes.

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

    • إذا كانت هناك تغييرات إضافية تريد إجراءها قبل تقديمها إلى QGIS، فاتبع الخطوات التالية:

      1. انتقل إلى نسختك المشتقة من QGIS-Documentation (https://github.com/<YourName>/QGIS-Documentation)

      2. انقر على githubBranch وابحث عن الفرع الجديد patch-xxx.

      3. اختره. سيعرض الزر githubBranch الآن Branch: patch-xxx.

      4. انتقل إلى القسم تعديل الملفات أدناه.

البديل 2: إنشاء فرع مخصص في مستودع التوثيق الخاص بك

يمكنك تحرير الملفات مباشرةً من نسختك المشتقة من توثيق QGIS.

أولًا، تأكد من أن الفرع master لديك محدَّث مع المصدر الأعلى (upstream)، أي الفرع qgis/QGIS-Documentation:master. وللقيام بذلك:

  1. انتقل إلى الصفحة الرئيسية لمستودعك، أي https://github.com/<YourName>/QGIS-Documentation. يجب أن يكون الفرع master نشطًا مع إشارة إلى ما إذا كان محدَّثًا مع qgis/QGIS-Documentation:master أم لا.

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

    إذا كانت لديه إيداعات متأخرة فقط:

    1. وسّع القائمة المنسدلة Sync fork على اليمين. ويمكنك:

      • Compare: مقارنة الفروع ورؤية التغييرات الجديدة في الفرع الأعلى التي لا توجد بعد في فرعك

      • Fetch and merge: يجلب التغييرات من الفرع الأعلى إلى فرعك.

    2. انقر على Fetch and merge: بعد انتهاء العملية، يُشار إلى فرعك بأنه محدَّث مع qgis/QGIS-Documentation:master.

  2. انقر على githubBranch في الزاوية العلوية اليسرى من مستودع QGIS-Documentation المشتق لديك وأدخل اسمًا فريدًا في حقل النص لإنشاء فرع جديد. يُنصح بأن يرتبط اسم الفرع الجديد بالمشكلة التي تنوي إصلاحها، فذلك مفيد لتمييز الفرع لاحقًا.

  3. اضغط على Create branch <branch_name> from master. يجب أن يعرض الزر githubBranch الآن branch_name.

  4. أنت جاهز الآن للبدء بتغييرات جديدة على فرعك الجديد.

تنبيه

أجرِ تغييراتك في فرع مخصص، ولا تجرها أبدًا في الفرع master مباشرةً

جرى العرف على تجنب إجراء تغييرات في الفرع master لديك إلا عند دمج التعديلات من الفرع master في qgis/QGIS-Documentation إلى نسختك من مستودع QGIS-Documentation. فالفروع المنفصلة تتيح لك العمل على عدة مشكلات في الوقت نفسه دون التداخل مع الفروع الأخرى. وإذا ارتكبت خطأ، فيمكنك دائمًا حذف الفرع والبدء من جديد بإنشاء فرع جديد من الفرع الرئيسي.

1.1.3. تعديل الملفات

  1. تأكد من أن الفرع الذي تريد تعديله نشط: يظهر اسمه في القائمة العلوية اليسرى أو في عنوان URL للصفحة.

  2. تصفح الملفات المصدرية وصولًا إلى الملف الذي يحتاج إلى تعديل.

  3. اضغط على الزر githubEditPencil Edit this file.

  4. حدّث النص باتباع إرشادات الكتابة

  5. بعد الانتهاء من تعديل الملف، اضغط على Commit changes... وأضف عنوانًا قصيرًا يشرح تغييراتك. ويمكنك أيضًا تقديم شرح أكثر تفصيلًا إن لزم الأمر.

  6. تأكد من تحديد Commit directly to the <branch_name> branch.

  7. اضغط على Commit changes لحفظ تعديلاتك في الفرع.

  8. لتحديث ملف صورة أو إضافة ملف جديد:

    1. تصفح فرعك وصولًا إلى مجلد الملف المراد تحديثه أو إضافته.

    2. في أعلى اليمين، استخدم القائمة Add files ► Upload files لاختيار الملفات من قرصك وتحميلها. ويمكنك العثور على تلميحات حول تنسيق الصور للتوثيق في إدارة لقطات الشاشة.

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

    4. أودِع تغييراتك مرة أخرى في الفرع الهدف.

  9. كرر الخطوات السابقة لأي ملفات أخرى تحتاج إلى تحديث لإصلاح المشكلة.

1.1.4. شارك تغييراتك عبر طلب سحب

عليك إنشاء طلب سحب لدمج تغييراتك في التوثيق الرسمي.

ابدأ طلب سحب جديدًا

  1. إذا استخدمت الرابط Edit on GitHub، فبعد إيداع تغييراتك يفتح GitHub تلقائيًا صفحة جديدة تقارن التغييرات التي أجريتها في الفرع patch-xxx لديك بالفرع qgis/QGIS-Documentation:master.

  2. في جميع الحالات، يمكن الوصول إلى صفحة مقارنة التغييرات بالانتقال إلى صفحة "Pull requests" في مستودعك والنقر على New pull request.

مقارنة التغييرات

إذا رأيت مربعي حوار، أحدهما يقول base:master والآخر compare:branch_name (انظر الشكل)، فسيؤدي ذلك فقط إلى دمج تغييراتك من أحد فروعك إلى الفرع الرئيسي لديك. لإصلاح ذلك انقر على الرابط compare across forks.

../../_images/githubCompareAcrossForks.png

شكل 1.8 إذا بدت صفحة Comparing changes لديك هكذا، فانقر على الرابط compare across forks.

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

  • base fork: النسخة المشتقة التي تريد دمج تغييراتك فيها

  • base: فرع النسخة المشتقة الأساسية الذي تريد دمج تغييراتك فيه

  • head fork: النسخة المشتقة التي تحتوي على التغييرات التي تريد ضمها إلى النسخة الأساسية

  • compare: الفرع الذي يحتوي على تلك التغييرات

اختر qgis/QGIS-Documentation نسخةً أساسية (base fork) مع master فرعًا أساسيًا (base)، واضبط head fork على مستودعك <YourName>/QGIS-Documentation، واضبط compare على فرعك المعدَّل.

../../_images/githubCreatePullRequestComparison.png

شكل 1.9 مقارنة التغييرات بين qgis/QGIS-Documentation ومستودعك

تُظهر علامة التحقق الخضراء مع عبارة Able to merge أن تغييراتك يمكن دمجها في التوثيق الرسمي دون تعارضات.

انقر على الزر Create pull request.

تحذير

إذا رأيت githubCantMerge

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

نصيحة

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

صِف طلب السحب

سيُفتح مربع نص: املأ عنوانًا وأي وصف ذي صلة بالتغييرات التي تقترحها.

إذا كان الطلب مرتبطًا بمشكلة معينة، فأضف رقم المشكلة إلى تعليقاتك. ويتم ذلك بإدخال # ثم رقم المشكلة (مثل #1234). وإذا سُبق بكلمات مثل fix أو close، فستُغلق المشكلة المعنية بمجرد دمج طلب السحب.

أضف روابط لأي صفحات توثيق تغيّرها.

انقر على Create pull request.

مراجعة طلب السحب والتعليق عليه

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

لمراجعة طلب سحب:

  1. انتقل إلى صفحة طلبات السحب وانقر على طلب السحب الذي تريد التعليق عليه.

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

  3. لإضافة تعليقات على أسطر محددة:

    1. انقر على githubFilesChanged وابحث عن الملف الذي تريد التعليق عليه. قد تحتاج إلى النقر على < > Display the source diff لرؤية التغييرات.

    2. مرّر إلى السطر الذي تريد التعليق عليه وانقر على githubBluePlus. سيفتح ذلك مربع نص يتيح لك كتابة تعليق.

يمكن نشر التعليقات على أسطر محددة بإحدى طريقتين:

  • كتعليقات منفردة، باستخدام الزر Add single comment. تُنشر هذه التعليقات فور كتابتها. استخدم هذه الطريقة فقط إذا كان لديك عدد قليل من التعليقات أو عند الرد على تعليق آخر.

  • أو كجزء من مراجعة، بالضغط على الزر Start a review. لا تُرسل تعليقاتك تلقائيًا بعد التأكيد، مما يتيح لك تعديلها أو إلغاءها لاحقًا، وإضافة ملخص للنقاط الرئيسية في المراجعة أو تعليمات عامة بخصوص طلب الدمج (pull request)، وتحديد ما إذا كنت توافق عليه أم لا. هذه هي الطريقة المريحة لأنها أكثر مرونة وتتيح لك تنظيم مراجعتك وتعديل التعليقات والنشر عندما تكون جاهزًا وإرسال إشعار واحد لمتابعي المستودع بدلًا من إشعار لكل تعليق. اطّلع على مزيد من التفاصيل.

../../_images/githubAddLineComment.png

شكل 1.10 التعليق على سطر مع اقتراح تغيير

يمكن أن تتضمن التعليقات على الأسطر اقتراحات يستطيع كاتب طلب الدمج تطبيقها على الطلب. لإضافة اقتراح، انقر على الزر githubSuggestions Insert a suggestion أعلى مربع نص التعليق وعدّل النص داخل كتلة الاقتراح.

نصيحة

يُفضّل إيداع الاقتراحات في طلب الدمج الخاص بك دفعةً واحدة

بصفتك كاتب طلب الدمج، عند دمج ملاحظات المراجعين مباشرة في طلبك، تجنّب استخدام الزر Commit suggestion أسفل التعليق عندما يكون لديك اقتراحات كثيرة لمعالجتها، وفضّل إضافتها كإيداع (commit) واحد مجمّع، أي:

  1. انتقل إلى التبويب githubFilesChanged

  2. اضغط على Add suggestion to batch لكل إعادة صياغة تريد تضمينها. سترى عدّادًا يزداد مع تقدّمك.

  3. اضغط على أيٍّ من أزرار Commit suggestions عندما تكون جاهزًا لتطبيق الاقتراحات على طلب الدمج، وأدخل رسالة تصف التغييرات.

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

إجراء التصحيحات

سيُضاف طلب الدمج الجديد تلقائيًا إلى قائمة طلبات الدمج. سيراجع المحررون والمسؤولون الآخرون طلبك، وقد يقدّمون اقتراحات أو يطلبون تصحيحات.

سيؤدي طلب الدمج أيضًا إلى تشغيل فحوصات بناء آلية (مثل تنسيق rst وصياغة شيفرات python)، وتُعرض التقارير أسفل الصفحة. إذا عُثر على خطأ، ستظهر علامة × حمراء بجانب الإيداع الخاص بك. انقر على العلامة الحمراء أو على Details في قسم الملخص أسفل صفحة طلب الدمج لرؤية تفاصيل الخطأ. سيتعيّن عليك إصلاح أي أخطاء أو تحذيرات مُبلّغ عنها قبل إيداع تغييراتك في المستودع qgis/QGIS-Documentation.

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

  1. انقر على التبويب githubFilesChanged في صفحة طلب الدمج

  2. اضغط على القائمة ... على يمين اسم الملف الذي تريد تعديله، واختر Edit file.

  3. يُفتح الملف في وضع التحرير؛ أضف تعديلاتك وقم بالإيداع.

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

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

سيدمج أحد المسؤولين مساهمتك بعد تصحيح أي أخطاء في البناء، وبعد أن تكون أنت والمسؤولون راضين عن تغييراتك.

1.1.5. حذف الفرع المدموج

يمكنك حذف الفرع بعد دمج تغييراتك. يجنّبك حذف الفروع القديمة وجود فروع غير مستخدمة وقديمة في مستودعك.

  1. انتقل إلى نسختك المتفرعة (fork) من مستودع QGIS-Documentation (https://github.com/<YourName>/QGIS-Documentation).

  2. انقر على التبويب Branches. ستجد تحت Your branches قائمة بفروعك.

  3. انقر على الأيقونة deleteSelected Delete this branch لحذف أي فروع غير مرغوب فيها.

1.2. استخدام أدوات سطر أوامر Git

واجهة الويب في GitHub طريقة سهلة لتحديث مستودع QGIS-documentation بمساهماتك، لكنها لا توفر أدوات من أجل:

  • تجميع إيداعاتك وتنظيف سجل تغييراتك

  • إصلاح التعارضات المحتملة مع المستودع الرئيسي

  • بناء الوثائق لاختبار تغييراتك

تحتاج إلى تثبيت Git على قرصك الصلب للوصول إلى أدوات أكثر تقدمًا وقوة والحصول على نسخة محلية من المستودع. نعرض أدناه بعض الأساسيات التي قد تحتاجها كثيرًا. ستجد أيضًا قواعد ينبغي مراعاتها حتى لو اخترت واجهة الويب.

في أمثلة الشيفرة أدناه، تُظهر الأسطر التي تبدأ بـ $ الأوامر التي يجب أن تكتبها، بينما الأسطر التي تبدأ بـ # تعليقات.

1.2.1. المستودع المحلي

أنت الآن جاهز للحصول على نسخة محلية (clone) من مستودع QGIS-Documentation الخاص بك.

يمكنك استنساخ مستودع QGIS الخاص بك باستخدام عنوان URL للويب كما يلي:

# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone https://github.com/<YourName>/QGIS-Documentation.git

سطر الأوامر السابق مجرد مثال. يجب أن تعدّل كلًّا من المسار وعنوان URL للمستودع، مع استبدال <YourName> باسم المستخدم الخاص بك في GitHub.

تحقق مما يلي:

# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin  https://github.com/<YourName>/QGIS-Documentation.git (fetch)
origin  https://github.com/<YourName>/QGIS-Documentation.git (push)
$ git branch
* master

  • origin هو اسم المستودع البعيد لمستودع QGIS-Documentation الخاص بك.

  • master هو الفرع الرئيسي الافتراضي. يجب ألا تستخدمه أبدًا للمساهمة! أبدًا!

بدلًا من ذلك، يمكنك استنساخ مستودع QGIS الخاص بك باستخدام بروتوكول SSH:

# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone git@github.com:<YourName>/QGIS-Documentation.git

نصيحة

هل ظهر خطأ Permission denied (publickey)؟

إذا ظهر لك الخطأ Permission denied (publickey) مع الأمر السابق، فقد تكون هناك مشكلة في مفتاح SSH الخاص بك. راجع مساعدة GitHub للتفاصيل.

تحقق مما يلي إذا استخدمت بروتوكول SSH:

# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin  git@github.com:<YourName>/QGIS-Documentation.git (fetch)
origin  git@github.com:<YourName>/QGIS-Documentation.git (push)
$ git branch
* master

يمكنك البدء بالعمل هنا، لكن على المدى الطويل ستواجه مشكلات كثيرة عند دفع مساهمتك (تُسمّى Pull Request في آلية عمل GitHub)، لأن الفرع master في مستودع qgis/QGIS-Documentation سيتباعد عن مستودعك المحلي/البعيد. لذا تحتاج إلى متابعة المستودع البعيد الرئيسي والعمل باستخدام الفروع.

1.2.2. إضافة مستودع بعيد آخر

لتتمكن من متابعة العمل في المشروع الرئيسي، أضف مستودعًا بعيدًا جديدًا في مستودعك المحلي. هذا المستودع البعيد الجديد هو مستودع QGIS-Documentation التابع لمشروع QGIS:

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

وبالمثل، يمكنك استخدام بروتوكول SSH لإضافة مستودع بعيد في مستودعك المحلي:

$ git remote add upstream git@github.com:qgis/QGIS-Documentation.git
$ git remote -v
origin  git@github.com:<YourName>/QGIS-Documentation.git (fetch)
origin  git@github.com:<YourName>/QGIS-Documentation.git (push)
upstream        git@github.com:qgis/QGIS-Documentation.git (fetch)
upstream        git@github.com:qgis/QGIS-Documentation.git (push)

أصبح لديك الآن خيار بين مستودعين بعيدين:

  • origin لدفع فرعك المحلي إلى مستودعك البعيد الخاص بك

  • upstream لدمج مساهمتك في المستودع الرسمي (إذا كان لديك الحق في ذلك) أو لتحديث الفرع master في مستودعك المحلي من الفرع master في المستودع الرسمي.

ملاحظة

upstream مجرد تسمية، أي اسم متعارف عليه، لكن يمكنك تسميته كما تشاء.

1.2.3. تحديث الفرع الأساسي

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

# switch to master branch (it is easy to forget this step!)
$ git checkout master
# get "information" from the master branch in the upstream repository
# (aka qgis/QGIS-Documentation's repository)
$ git fetch upstream master
# merge update from upstream/master to the current local branch
# (which should be master, see step 1)
$ git merge upstream/master
# update **your** remote repository (aka <YourName>/QGIS-Documentation)
$ git push origin master

أصبح لديك الآن مستودعان محلي وبعيد، كلاهما فرعه master محدّث وفق الفرع master الرسمي لـ QGIS-Documentation. يمكنك البدء بالعمل على مساهمتك.

ملاحظة

بدّل الفرع إذا أردت المساهمة في الوثائق المُصدَرة

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

1.2.4. المساهمة في فرع العمل الخاص بك

الآن بعد أن حُدّث الفرع الأساسي، تحتاج إلى إنشاء فرع مخصص تضيف فيه مساهمتك. اعمل دائمًا على فرع غير الفرع الأساسي! دائمًا!

# Create a new branch
$ git checkout -b myNewBranch
# checkout means go to the branch
# and -b flag creates a new branch if needed, based on current branch
# Let's check the list of existing branches (* indicates the current branch)
$ git branch
master
release_2.18
...
* myNewBranch
# You can now add your contribution, by editing the concerned file(s)
# with any application (in this case, vim is used)
$ vim myFile
# once done
$ git add myFile
$ git commit

كلمات قليلة حول أوامر commit/push:

  • حاول إيداع مساهمة واحدة فقط (تغيير ذرّي)، أي عالج مشكلة واحدة فقط

  • حاول أن تشرح بعناية ما غيّرته في عنوان الإيداع وفي وصفه. السطر الأول عنوان، ويجب أن يبدأ بحرف كبير وألا يتجاوز طوله 80 حرفًا، ولا تنهِه بـ .. كن موجزًا. يمكن أن يكون وصفك أطول وينتهي بـ . ويمكنك تقديم تفاصيل أكثر بكثير.

  • استخدم # متبوعة برقم للإشارة إلى مشكلة. أضف البادئة Fix إذا كنت تصلح التذكرة: سيغلق إيداعك التذكرة.

الآن بعد أن حُفظت تغييراتك وأُودعت في فرعك المحلي، تحتاج إلى إرسالها إلى مستودعك البعيد لإنشاء طلب دمج:

$ git push origin myNewBranch

1.2.5. مشاركة تغييراتك

يمكنك الآن الانتقال إلى مستودعك في GitHub و إنشاء طلب دمج كما شُرح في قسم سابق. تأكد من إنشاء طلب الدمج من فرعك إلى الفرع البعيد الذي تستهدفه في مستودع QGIS-Documentation الرسمي.

1.2.6. تنظيف مستودعك المحلي والبعيد

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

# delete local branch
$ git branch -d myNewBranch
# Remove your remote myNewBranch by pushing nothing to it
$ git push origin :myNewBranch

ولا تنسَ تحديث الفرع master في مستودعك المحلي!

1.3. قراءة متعمقة

  • إلى جانب واجهة الويب في GitHub وأدوات سطر أوامر Git المعروضة أعلاه، توجد أيضًا تطبيقات بواجهة رسومية يمكنك استخدامها لإنشاء مساهماتك في الوثائق وإدارتها.

  • عندما تتعارض التغييرات في طلب الدمج مع تغييرات حديثة دُفعت إلى الفرع المستهدف، يجب حل التعارضات قبل أن يصبح الدمج ممكنًا:

    • إذا كان التعارض يتعلق بأسطر قليلة متنافسة، يتوفر الزر Resolve conflicts في صفحة طلب الدمج على GitHub. اضغط على الزر وحُلّ المشكلة كما هو موضح في حل تعارض الدمج على GitHub

    • إذا كان التعارض يتضمن إعادة تسمية ملفات أو حذفها، فستحتاج إلى حله باستخدام أسطر أوامر Git. عادةً، عليك أولًا إعادة تأسيس (rebase) فرعك على الفرع المستهدف باستدعاء git rebase targetBranch ثم إصلاح التعارضات المُبلّغ عنها. اقرأ المزيد في حل تعارض الدمج باستخدام سطر الأوامر

  • أحيانًا، في نهاية عملية المراجعة اللغوية، قد ينتهي بك الأمر بتغييرات موزعة على إيداعات متعددة لا داعي لها بالضرورة. تساعدك أسطر أوامر Git على ضغط (squash) هذه الإيداعات إلى عدد أقل ورسائل إيداع أوضح معنى. بعض التفاصيل في استخدام git rebase في سطر الأوامر