ساخت ترک‌ها

یک مسیر از بخش‌های مختلفی تشکیل شده است.

فراداده

پیکربندی و فراداده‌ی مسیر در فایل config.json مشخص می‌شود. این فایل تمرین‌ها، مفاهیم، تنظیمات ویرایشگر و موارد بسیار بیشتری از مسیر را فهرست می‌کند. مستندات config.json را ببینید.

مفاهیم

همه‌ی تمرین‌های مفهومی و عملی یک مسیر، مفاهیم را در بر می‌گیرند. این مفاهیم خودشان موجودیت‌های جداگانه‌ای هستند. برای اطلاعات بیشتر مستندات را ببینید.

مفاهیمی که در تمرین‌های مفهومی مسیر آموزش داده می‌شوند، یک برنامه‌ی درسی را تشکیل می‌دهند. برنامه‌ی درسی به‌صورت یک نقشه‌ی مفهومی به دانش‌آموزان نشان داده می‌شود. برای یادگیری درباره‌ی ساخت نقشه‌ی مفهومی برای یک برنامه‌ی درسی، مستندات نقشه‌ی مفهومی را ببینید.

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

تمرین‌ها

مسیر دو نوع تمرین دارد:

• تمرین‌های مفهومی: برای آموزش یک یا چند مفهوم به یک دانش‌آموز طراحی شده‌اند. برای اطلاعات بیشتر مستندات را ببینید.
• تمرین‌های عملی: برای تمرین مفاهیم آموخته‌شده طراحی شده‌اند. برای اطلاعات بیشتر مستندات را ببینید.

Dig Deeper

هر تمرین یک بخش اختیاری Dig Deeper دارد که می‌تواند شامل موارد زیر باشد:

• رویکردها: روش‌های مختلفی که تمرین می‌تواند با آن‌ها حل شود
• مقاله‌ها: جنبه‌های جالب تمرین را توصیف می‌کنند
• ویدیوهای انجمن: ویدیوهایی که تمرین را نشان می‌دهند، معمولاً با حل کردن تمرین از صفر توسط یک نفر

فایل‌های مشترک

برخی فایل‌ها مخصوص تمرین‌های جداگانه نیستند، بلکه برای همه‌ی تمرین‌ها کاربرد دارند. برای اطلاعات بیشتر مستندات را ببینید.

مستندات

هر مسیر چند فایل مستندات ضروری دارد. برای اطلاعات بیشتر مستندات را ببینید.

ویجت‌ها

برخی بخش‌های مسیر می‌توانند در ویجت‌ها نمایش داده شوند.

راهنمای سبک

همه‌ی اسناد باید از راهنمای سبک پیروی کنند. اسناد Markdown نیز باید از استانداردهای Markdown ما پیروی کنند.

مثال

csharp
├── config
|   ├── exercise_readme.go.tmpl
|   └── maintainers.json
├── docs
|   ├── ABOUT.md
|   ├── INSTALLATION.md
|   ├── LEARNING.md
|   ├── RESOURCES.md
|   └── TESTS.md
├── concepts
|   └── numbers
|       ├── about.md
|       ├── introduction.md
|       └── links.json
└── exercises
|   ├── concept
|   |   └── cars-assemble
|   |       ├── .docs
|   |       |   ├── hints.md
|   |       |   ├── introduction.md
|   |       |   └── instructions.md
|   |       ├── .meta
|   |       |   ├── config.json
|   |       |   ├── design.md
|   |       |   └── Exemplar.cs (track-specific)
|   |       ├── CarsAssemble.cs (track-specific)
|   |       ├── CarsAssemble.csproj (track-specific)
|   |       └── CarsAssembleTests.cs (track-specific)
|   ├── practice
|   |   └── leap
|   |       └── .docs
|   |       |   └── instructions.md
|   |       └── .meta
|   |       |   ├── config.json
|   |       |   └── Example.cs (track-specific)
|   |       ├── Leap.cs (track-specific)
|   |       ├── Leap.csproj (track-specific)
|   |       └── LeapTests.cs (track-specific)
|   └── shared
|       └── .docs
|           ├── debug.md
|           ├── help.md
|           └── tests.md
└── config.json

نگهداری

مجوزهای مخزن

به هر مسیر به‌طور خودکار یک دسته‌بندی نگهداری اختصاص داده می‌شود که مجوزهای مخزن GitHub نگهدارنده‌ی مسیر را تعیین می‌کند.

اجتناب از ایجاد اجراهای Test غیرضروری

وقتی یک PR مسیر را که به یک تمرین دست می‌زند ادغام می‌کنید، باعث می‌شود همه‌ی آخرین نسخه‌های منتشرشده‌ی راه‌حل‌های دانش‌آموزان دوباره Test شوند. برای تمرین‌های محبوب، این یک عملیات بسیار پرهزینه است (۷۰٬۰۰۰ اجرای Test برای Hello World در Python به‌عنوان یک نمونه‌ی حاد!).

از شما می‌خواهیم سعی کنید این کار را بی‌دلیل انجام ندهید.

راه‌حل‌ها دوباره Test نمی‌شوند اگر کامیت ادغام‌شده یا:

• فقط فایل‌های .docs یا .meta یا فایل‌های دیگری را لمس کند که کاربران با آن‌ها تعامل ندارند
• یا در بدنه‌ی کامیت شامل [no important files changed] باشد.

راه‌حل‌ها دوباره Test می‌شوند اگر کامیت ادغام‌شده هر دو شرط زیر را داشته باشد:

• در بدنه‌ی کامیت [no important files changed] را نداشته باشد
• و یکی از فایل‌های زیر را برای یک تمرین لمس کند (همان‌طور که در فایل .meta/config.json آن مشخص شده است):
  • فایل‌های Test
  • فایل‌های ویرایشگر
  • فایل‌های invalidator

چند مثال:

• Python#۳۴۲۳: فقط مستندات را لمس می‌کند، بنابراین هیچ Testی اجرا نشد
• Python#۳۴۳۷: با [no important files changed] اضافه‌شده ادغام شد، بنابراین هیچ Testی اجرا نشد
• Csharp#۲۱۳۸: فاصله‌های خالی از Testها حذف شد. کلیدواژه اضافه نشد. Testها بی‌دلیل دوباره اجرا شدند.