دليل طلبات السحب للمشرفين

بصفتك مشرفًا، فإن مراجعة Pull Requests أمر ستقوم به بانتظام إلى حدّ ما. يتضمّن هذا المستند بعض الإرشادات الخاصة بـ Exercism لمراجعة Pull Requests.

مراجعة Pull Requests الخاصة بالتمارين

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

وللمساعدة في تبسيط سير العمل هذا، طوّرنا التوصيات التالية.

توصية: أن يتولّى مشرف خبير واحد المراجعة الأولى

أسباب قصر المراجعة الأولى على مشرف خبير واحد بالضبط هي:

  • عدم تكرار عمل المراجعة
  • سيعمل المساهم والمشرف كثنائي على Pull Request، مما يمنح المساهم، على الأرجح، الإحساس بأنه لا يفعل هذا وحده
  • لن تظهر تعليقات مراجعة متضاربة من مشرفين آخرين

توصية: الدمج مع الحالة wip

بمجرد أن يرضى المساهم والمشرف معًا عن التمرين، ينبغي دمج التمرين مع تعيين status الخاص به إلى wip (قيد العمل). لن تكون التمارين التي تحمل هذه الحالة متاحة للطلاب، لكنها ستكون متاحة للاطلاع لأبرز مرشدينا (بمجرد أن ننفّذ ذلك في وقت ما في المستقبل). يمكن لهؤلاء المستخدمين ذوي السمعة العالية حينها تجربة التمرين وإنشاء issues أو Pull Requests لإصلاح التمرين أو تحسينه.

أهم مزايا هذا الأسلوب هي:

  • يرفع العبء عن ثنائي المساهم/المشرف الأصلي في بلوغ الكمال في كل شيء
  • لا يؤدي إلى دورات ضخمة من مراجعات Pull Request بأصوات متعددة (وهو أمر يصعب إدارته فعلًا)

مراجعة Pull Requests الخاصة بالتمارين التدريبية

توصية: التفكير فيما إذا كان التغيير ينتمي فعلًا إلى problems-specifications

بعض محتويات التمرين التدريبي (مثل مقدمته) تأتي من بياناته الوصفية (المشتركة) كما هي معرّفة في مستودع problems-specifications. عند مراجعة Pull Request يغيّر محتوى كهذا، فكّر فيما إذا كان التغيير قد يفيد مسارات أخرى أيضًا. وإذا كان الأمر كذلك، فاقترح على المساهم فتح Pull Request للملف المقابل في مستودع problems-specifications.

توصيات عامة للمراجعة

توصية: مراجع أساسي واحد لكل Pull Request

ينبغي أن يكون لكل Pull Request مراجع أساسي واحد (أيًا كان المشرف الذي يتولّاه). أما بقية المشرفين و/أو أعضاء المجتمع فينبغي أن يؤدوا دورًا ثانويًا.

هناك طريقتان رئيسيتان يمكن لمن في دور ثانوي أن يساهم بهما في المراجعة:

  • التدقيق في الإملاء والقواعد، لكن فقط بعد أن ينتهي المراجع الأساسي من مراجعته الأولى. قد يكون محبطًا للمساهمين أن يتلقّوا مراجعة إملائية/نحوية، فيصلحوا ما فيها، ثم يأتي مشرف ويطلب منهم إجراء تغييرات أكثر جوهرية. بعبارة أخرى: التدقيق اللغوي شيء تفعله بعد الانتهاء من التغييرات الجوهرية (أو ربما في Pull Request لاحق).
  • الإشارة إلى أمور بطريقة لا تطلب من المراجع تنفيذ أي إجراء. إذا علّقت على أمور ينبغي للمراجع الأساسي التفكير فيها أو ربما فاتته، فانشر تعليقك على شكل إبداء رأي أو بصيغة سؤال. فهذا يوضّح للمساهم أنك لا تطلب منه إجراء تغييرات، مما يقلّل اللبس عليه. كما يقلّل من احتمال أن يشعر المراجع الأساسي بأنه "مُنتقَص من دوره".

توصية: لا تعلّق على أمور غير ذات صلة

عند مراجعة Pull Request، علّق فقط على الأمور المتعلقة مباشرة بـ Pull Request. أما أي شيء آخر، فيرجى فتح issue أو إنشاء Pull Request منفصل (لاحق).

توصية: اربط بالتوثيق

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

توصية: اطلب المساعدة من فرق أخرى

إذا أردت طلب المساعدة في مراجعة Pull Request، فلدينا فريقان محددان يمكنك مناداتهما:

  • @exercism/reviewers: لأي مراجعات عامة
  • @exercism/github-actions: لأي أسئلة تتعلق بـ GitHub actions