أضف التمرين الأول

التمرين الأول في كل مسار هو تمرين "Hello, World!" بسيط للغاية.

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

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

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

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

تخضع تمارين "Hello, World!" لبعض القواعد الخاصة:

  • تكون دائمًا التمرين الأول في المسار
  • يجب أن ينفّذها كل مسار
  • يحتوي ملف الاختبارات على اختبار واحد فقط
  • يحتوي ملف الهيكل على تنفيذ يعمل تقريبًا، لكنه يستخدم "Goodbye, Mars!" بدلًا من "Hello, World!"
  • لا يحتوي على prerequisites
  • لا يحتوي على practices

تحديد مسارات الملفات

يتطلب تمرين "Hello, World!" (وفي الحقيقة، جميع التمارين على Exercism) مجموعة محددة من الملفات:

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

قبل أن ننشئ تمرين "Hello, World!"، عليك اتخاذ بعض القرارات بشأن أسماء الملفات ومساراتها الخاصة بالمسار (مجموعة الاختبارات، وتنفيذ الهيكل، والتنفيذ النموذجي، وأي ملفات إضافية).

القاعدة العامة هي استخدام أسماء معتادة في تلك اللغة. وحيث لا توجد تفضيلات قوية، فضّل هياكل مجلدات أقل تعمقًا. سيحتاج سكربت CI إلى التعرف على التنفيذ النموذجي، لذا يُستحسن اختيار اسم أساسي عام يمكن أن تستخدمه جميع التمارين، مثل example أو sample أو reference-solution.

تهيئة مسارات الملفات

بعد اختيار مسارات الملفات الخاصة بالمسار، عليك تهيئتها في مفتاح files داخل ملف config.json الجذري. سيعمل مفتاح files قالبًا لجميع التمارين، ما يسمح لأي أدوات (سنستخدم بعضها بعد قليل) بمعرفة أين تبحث عن الملفات. ويمكنك استخدام عناصر نائبة متنوعة لتسهيل تهيئة معرّف التمرين (hello-world في هذه الحالة).

مثال

إذا كان مسارك يستخدم PascalCase في أسماء ملفاته، فقد يبدو مفتاح files هكذا:

"files": {
  "solution": [
    "%{pascal_slug}.cs"
  ],
  "test": [
    "%{pascal_slug}Tests.cs"
  ],
  "example": [
    ".meta/Example.cs"
  ]
}
Note

ينبغي تخزين ملف (أو ملفات) المثال داخل دليل .meta.

لمزيد من المعلومات، اطّلع على توثيق مفتاح files.

إنشاء الملفات

بعد تحديد قوالب مسارات الملفات، يمكنك عندئذ إنشاء ملفات تمرين "Hello, World!" بسرعة بتشغيل الأوامر التالية من الدليل الجذري للمسار:

bin/fetch-configlet
bin/configlet create --practice-exercise hello-world

تعيين المؤلف

لكي يعرض الموقع اسمك كمؤلف للتمرين، اتبع هذه الخطوات:

داخل ملف .meta/config.json الخاص بالتمرين:

  • أضف اسم المستخدم الخاص بك على GitHub إلى مفتاح authors

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

Note

يُمنح مؤلفو التمارين أيضًا السمعة

استخدام السكربت

يمكن لمستودعات المسارات الأحدث استخدام سكربت bin/add-practice-exercise (المصدر) لإضافة تمارين جديدة:

bin/add-exercise -a <github_username> two-fer
Note

إذا كنت تعمل على مستودع مسار لا يحتوي على هذا الملف، فلا تتردد في نسخه إلى مستودعك باستخدام رابط المصدر أعلاه.

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

بعد إنشاء الملفات الأولية، سيتعين عليك عندئذ:

  • إضافة اختبارات إلى ملف الاختبارات
  • إضافة تنفيذ نموذجي
  • تحديد محتوى ملف الهيكل

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

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

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

في تمرين "Hello, World!" ستكون هناك حالة اختبار واحدة فقط، لذا سيكون أي من الخيارين مناسبًا.

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

ينبغي أن يحتوي ملف التنفيذ النموذجي على الكود المطلوب لاجتياز الاختبارات.

تحديد الهيكل

ينبغي أن يحتوي ملف الهيكل على حل شبه عامل للاختبارات، لكن مع استبدال نص "Hello, World!" بـ "Goodbye, Mars!". نصيحة: يمكنك ببساطة نسخ حل المثال ولصقه وتعديله.

تحديث مؤلف (مؤلفي) التمرين

بعد أن تنتهي من التمرين، يُرجى إضافة اسم المستخدم الخاص بك على GitHub إلى مصفوفة "authors" في ملف .meta/config.json الخاص بالتمرين. سيضمن ذلك أن ننسب إليك فضل إنشاء التمرين بشكل صحيح.

التدقيق

للتحقق من أن التمرين مُعدّ بشكل صحيح، يمكنك استخدام وظيفة التدقيق المدمجة في أداة configlet.

الخطوة الأولى هي جلب أداة configlet، وقد أنشأنا لها سكربتين:

  • bin/fetch-configlet: شغّله إذا كنت تستخدم *nix أو macOS
  • bin/fetch-configlet.ps1: شغّله إذا كنت تستخدم Windows

تشغيل أحد هذين السكربتين من الدليل الجذري لمستودع المسار سيُنزّل الملف التنفيذي bin/configlet أو bin/configlet.exe على التوالي.

يمكنك بعد ذلك التحقق من صحة التمرين بتشغيل bin/configlet lint.

Note

من المحتمل أن يبلّغك configlet بالخطأ التالي:

The `tags` array is empty:
/path/to/track/config.json

سيُصلَح هذا الخطأ في خطوة الاستعداد للانطلاق، لذا إما أن:

  • تتجاهل الخطأ (في الوقت الحالي)، أو
  • تصلح الخطأ بإضافة وسوم
Note

سيشغّل سير عمل configlet أمر configlet lint تلقائيًا كلما تم دفع شيء إلى main أو إلى طلب سحب.