افزودن تمرین عملی

این سند توضیح می‌دهد چگونه یک تمرین عملی جدید اضافه کنید.

انتخاب تمرین

ساده‌ترین راه برای بررسی اینکه کدام تمرین‌های عملی هنوز پیاده‌سازی نشده‌اند این است که به صفحه‌ی ساخت مسیر بروید (برای مثال 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

از خروجی استفاده کنید تا مطمئن شوید همه‌چیز درست است.

ارسال Pull Request

وقتی همه‌چیز درست بود، می‌توانید یک Pull Request ارسال کنید به مخزن مسیر.

پیش از ارسال، لطفاً راهنمای Pull Request مشارکت‌کنندگان و راهنمای Pull Request را بخوانید.

مطمئن شوید که توضیحات PR تمرینی را که اضافه می‌شود ذکر کرده است.