إضافة تمرين تطبيق

يوضّح هذا المستند كيفية إضافة تمرين تدريبي جديد.

اختيار التمرين

أبسط طريقة للتحقق من التمارين التدريبية التي لم تُنفَّذ بعد هي الانتقال إلى صفحة بناء المسار (مثل https://exercism.org/tracks/csharp/build) وفحص قسم "التمارين التدريبية".

إنشاء هيكل التمرين

يمكنك إنشاء هيكل تمرين تدريبي جديد بسرعة عبر تشغيل السكربت bin/add-practice-exercise (المصدر) من الدليل الجذر للمسار:

bin/add-practice-exercise <exercise-slug>

ويمكنك اختياريًا أيضًا تحديد مستوى صعوبة التمرين (عبر -d) و/أو اسم المستخدم على GitHub للمؤلف (عبر -a):

bin/add-practice-exercise -d 3 -a foobar <exercise-slug>

تنفيذ التمرين

بعد إنشاء ملفات الهيكل، سيتعيّن عليك القيام بما يلي:

• إضافة اختبارات إلى ملف الاختبارات
• إضافة تنفيذ نموذجي
• تحديد محتوى الملف المبدئي
• داخل ملف .meta/config.json الخاص بالتمرين:
  • إضافة اسم المستخدم على GitHub لمؤلفي التمرين إلى المفتاح authors
• داخل ملف config.json الخاص بالمسار:
  • التحقق من صعوبة التمرين أو تحديثها
  • إضافة المفاهيم إلى المفتاح practices (مطلوب فقط عندما يحتوي المسار على تمارين مفاهيمية)
  • إضافة المفاهيم إلى المفتاح prerequisites (مطلوب فقط عندما يحتوي المسار على تمارين مفاهيمية)

إضافة الاختبارات

جزء أساسي من إضافة أي تمرين هو إضافة الاختبارات. بشكل تقريبي، لديك خياران عند إضافة اختبارات لتمرين تدريبي:

1. اكتب الاختبارات من الصفر، باستخدام حالات الاختبار من ملف canonical-data.json الخاص بالتمرين والموجود في مستودع problem-specifications.
2. انقل الاختبارات من تنفيذ مسار آخر (نصيحة: انتقل إلى https://exercism.org/exercises/<slug> للحصول على نظرة عامة على المسارات التي نفّذت تمرينًا معينًا).

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

إضافة تنفيذ نموذجي

للتأكد من إمكانية كتابة كود يجتاز الاختبارات، يجب إضافة تنفيذ نموذجي.

يمكنك التحقق من أن التنفيذ النموذجي يجتاز جميع الاختبارات بتشغيل السكربت bin/verify-exercises (المصدر) من الدليل الجذر للمسار:

bin/verify-exercises <exercise-slug>

استخدم المخرجات للتحقق من أن التنفيذ النموذجي يجتاز جميع الاختبارات.

إضافة الملفات المبدئية

توفّر ملفات التنفيذ المبدئية نقطة بداية للطلاب.

نوصي بأن تحتوي الملفات المبدئية على الحد الأدنى من الكود بحيث:

• يستطيع الطالب البدء فورًا في كتابة المنطق اللازم لاجتياز الاختبارات
• لا يواجه الطالب أخطاء صياغية "غريبة"

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

أمثلة

Python:

def two_fer(name):
    pass

Kotlin:

fun twofer(name: String): String {
    TODO("Implement the function to complete the task")
}

تدقيق التمرين

الخطوة الأخيرة هي تشغيل المدقّق للتحقق من أن ملفات المسار (وملفات الإعداد) مبنية بشكل صحيح، من حيث الصياغة ومن حيث الدلالة.

أولًا، تأكد من أن لديك أحدث إصدار من configlet بتشغيل:

bin/fetch-configlet

ثم شغّل المدقّق بتشغيل:

bin/configlet lint

استخدم المخرجات للتحقق من أن كل شيء على ما يرام.

إرسال طلب سحب

بمجرد أن يصبح كل شيء على ما يرام، يمكنك حينها إرسال طلب سحب إلى مستودع المسار.

قبل الإرسال، يُرجى قراءة دليل طلب السحب للمساهمين ودليل طلبات السحب.

تأكد من أن وصف طلب السحب يذكر التمرين المُضاف.