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

اولین تمرین در هر مسیر، یک تمرین بسیار ساده‌ی «Hello, World!» است.

هدف تمرین این است که سریع مطمئن شویم همه‌چیز درست به هم متصل شده است. این کار تأیید می‌کند که کاربر محیط برنامه‌نویسی را درست نصب کرده است، می‌داند testها را چطور اجرا کند و می‌تواند آن‌ها را پاس کند. علاوه بر این، برای کلاینت خط فرمان Exercism (CLI) هم تضمین می‌کند که کاربر CLI را درست نصب و پیکربندی کرده است و اینکه سایت فایل‌های درست تمرین را تحویل می‌دهد و هیچ فایل جانبی نالازمی ارسال نمی‌کند. در آخر هم تضمین می‌کند که کاربر با چرخه‌ی دانلود یک تمرین با CLI، حل مسئله در محیط توسعه‌ی محلی و ارسال راه‌حل به سایت آشناست.

به بیان دیگر، این‌جا هنوز واقعاً بحث یادگیری چیزی درباره‌ی خود زبان مطرح نیست. هدف ما چیزی بسیار ساده است.

این احتمالاً سخت‌ترین بخش راه‌اندازی درست مخزن مسیر هم خواهد بود، چون اجزای متحرک زیادی در پیاده‌سازی یک تمرین دخیل‌اند.

پیاده‌سازی تمرین

تمرین «Hello, World!» قواعد ویژه‌ی خودش را دارد:

• همیشه اولین تمرین در یک مسیر است
• هر مسیر باید آن را پیاده‌سازی کند
• فایل test تنها یک test دارد
• فایل stub یک پیاده‌سازی تقریباً کارآمد دارد، اما به‌جای «Hello, World!» از «Goodbye, Mars!» استفاده می‌کند
• هیچ prerequisites ندارد
• هیچ practices ندارد

تعیین مسیرهای فایل

تمرین «Hello, World!» (و در واقع، همه‌ی تمرین‌های Exercism) به مجموعه‌ی مشخصی از فایل‌ها نیاز دارد:

• مستندات: به دانشجو توضیح می‌دهد که چه کاری باید انجام دهد (می‌تواند به‌صورت خودکار تولید شود).
• فراداده: مقداری فراداده درباره‌ی تمرین در اختیار Exercism می‌گذارد (بیشتر آن می‌تواند به‌صورت خودکار تولید شود).
• مجموعه‌ی test: درستی راه‌حل را بررسی می‌کند (مخصوص مسیر).
• پیاده‌سازی stub: نقطه‌ی شروعی برای دانشجوها فراهم می‌کند (مخصوص مسیر).
• پیاده‌سازی نمونه: پیاده‌سازی نمونه‌ای فراهم می‌کند که همه‌ی testها را پاس می‌کند (مخصوص مسیر).
• فایل‌های تکمیلی: تضمین می‌کنند که testها بتوانند اجرا شوند (مخصوص مسیر، اختیاری).

پیش از آنکه بتوانیم تمرین «Hello, World!» را بسازیم، باید درباره‌ی نام‌ها و مسیرهای فایل مخصوص مسیر تصمیم‌هایی بگیرید (مجموعه‌ی test، پیاده‌سازی stub، پیاده‌سازی نمونه و هر فایل تکمیلی دیگری).

قاعده‌ی سرانگشتی این است که نام‌هایی را به کار ببرید که برای آن زبان طبیعی‌اند. جایی که ترجیح قوی‌ای وجود ندارد، ساختار دایرکتوری کم‌عمق‌تر را ترجیح دهید. پیاده‌سازی نمونه باید برای اسکریپت 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"
  ]
}

برای اطلاعات بیشتر، مستندات کلید files را ببینید.

ساختن فایل‌ها

پس از مشخص‌کردن قالب‌های مسیر فایل، می‌توانید با اجرای دستورهای زیر از دایرکتوری ریشه‌ی مسیر، فایل‌های تمرین «Hello, World!» را به‌سرعت بسازید:

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

تعیین نویسنده

برای اینکه وب‌سایت شما را به‌عنوان نویسنده‌ی تمرین فهرست کند، این مراحل را دنبال کنید:

داخل فایل .meta/config.json تمرین:

• نام کاربری GitHub خود را به کلید authors اضافه کنید

برای اینکه این کار انجام شود، باید حساب Exercism خود را به GitHub متصل کنید. این کار را می‌توانید در وب‌سایت، در بخش «Integrations» صفحه‌ی تنظیمات انجام دهید.

استفاده از اسکریپت

مخزن‌های مسیر تازه‌تر می‌توانند برای افزودن تمرین‌های جدید از اسکریپت bin/add-practice-exercise (منبع) استفاده کنند:

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

پیاده‌سازی تمرین

وقتی فایل‌های اسکلت‌بندی‌شده ساخته شدند، باید:

• testها را به فایل test اضافه کنید
• یک پیاده‌سازی نمونه اضافه کنید
• محتوای فایل stub را تعریف کنید

افزودن testها

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

1. testها را از صفر پیاده‌سازی کنید و از موارد test موجود در canonical-data.json تمرین استفاده کنید.
2. testها را از پیاده‌سازی یک مسیر دیگر منتقل کنید (نکته: به https://exercism.org/exercises/hello-world بروید تا ببینید کدام مسیرها یک تمرین خاص را پیاده‌سازی کرده‌اند).

برای تمرین «Hello, World!» فقط یک مورد test وجود خواهد داشت، پس هر دو گزینه خوب‌اند.

افزودن پیاده‌سازی نمونه

فایل پیاده‌سازی نمونه باید کدی را داشته باشد که برای حل testها لازم است.

تعریف stub

فایل stub باید راه‌حلی تقریباً کارآمد برای testها داشته باشد، اما متن «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 درستی تمرین را بررسی کنید.

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