configlet sync

همگام‌سازی داده‌های تمرین با مخزن problem-specifications

یک تمرین عملی در یک ترک Exercism اغلب بر پایه‌ی مشخصاتی در مخزن exercism/problem-specifications پیاده‌سازی می‌شود.

Exercism آگاهانه لازم می‌داند که هر تمرین نسخه‌ی خودش را از برخی فایل‌ها (مانند .docs/instructions.md) داشته باشد، حتی اگر آن تمرین در problem-specifications وجود داشته باشد. به همین دلیل configlet دستور sync را دارد که می‌تواند بررسی کند آیا تمرین‌های عملی ترک با آن منبع بالادستی همگام‌اند یا نه، و در صورت در دسترس بودن به‌روزرسانی، آن‌ها را به‌روزرسانی کند.

سه نوع داده وجود دارد که می‌توان آن‌ها را از problem-specifications به‌روزرسانی کرد: مستندات، فراداده و تست‌ها. یک نوع داده دیگر هم هست که می‌توان آن را از فایل config.json سطح ترک پر کرد: مسیرهای فایل در فایل‌های پیکربندی تمرین.

بررسی و به‌روزرسانی این انواع داده را در بخش‌های جداگانه در ادامه توضیح می‌دهیم، اما به‌عنوان یک خلاصه‌ی سریع:

• configlet sync فقط روی تمرین‌هایی کار می‌کند که در فایل config.json سطح ترک وجود دارند. بنابراین اگر در حال پیاده‌سازی تمرین جدیدی در یک ترک هستید و می‌خواهید فایل‌های اولیه را با configlet sync اضافه کنید، لطفاً ابتدا تمرین را به فایل config.json سطح ترک اضافه کنید. اگر تمرین هنوز آماده‌ی نمایش به کاربران نیست، لطفاً مقدار status آن را روی wip بگذارید.
• یک configlet sync ساده هیچ تغییری در ترک ایجاد نمی‌کند و همه‌ی انواع داده را برای همه‌ی تمرین‌ها بررسی می‌کند.
• برای کار روی زیرمجموعه‌ای از انواع داده، از ترکیبی از گزینه‌های --docs، --filepaths، --metadata و --tests استفاده کنید.
• برای به‌روزرسانی تعاملی داده‌ها در ترک، از گزینه‌ی --update استفاده کنید.
• برای به‌روزرسانی غیرتعاملی مستندات، مسیرهای فایل و فراداده در ترک، از --update --yes استفاده کنید.
• برای گنجاندن غیرتعاملی همه‌ی تست‌های دیده‌نشده‌ی یک تمرین مشخص، مثلاً از --update --tests include --exercise prime-factors استفاده کنید.
• برای صرف‌نظر کردن از دانلود مخزن problem-specifications، این گزینه‌ها را اضافه کنید: --offline --prob-specs-dir /path/to/local/problem-specifications
• توجه کنید که configlet sync هنگام به‌روزرسانی می‌کوشد ترتیب کلیدها را در فایل‌های .meta/config.json تمرین حفظ کند. برای نوشتن این فایل‌ها به شکلی استاندارد و بدون همگام‌سازی، لطفاً از دستور configlet fmt استفاده کنید. با این حال، configlet sync کلیدهای الزامی (که ممکن است خالی باشند) مانند authors، files و blurb را در صورت نبودن اضافه می‌کند. این کار کمتر شبیه همگام‌سازی است، اما راحت‌تر است: هنگام پیاده‌سازی تمرین جدیدی می‌توانید از sync برای ساختن یک فایل .meta/config.json اولیه استفاده کنید.
• configlet sync کلیدهایی را که در مشخصات نیستند حذف می‌کند. جفت‌های کلید/مقدار سفارشی همچنان پشتیبانی می‌شوند: باید داخل یک شیء JSON به نام custom نوشته شوند.
• کد خروج ۰ است اگر هنگام خروج configlet همه‌ی داده‌های دیده‌شده همگام شده باشند، و در غیر این صورت ۱ است.

توجه کنید که در انتشارهای configlet تا نسخه‌ی 4.0.0-alpha.34 و پیش‌تر از آن، دستور sync فقط روی تست‌ها کار می‌کرد.

کاربرد

دستور sync را می‌توان برای بررسی یا به‌روزرسانی مستندات، فراداده و تست‌های تمرین‌های عملی از مخزن problem-specifications به کار برد. همچنین می‌تواند مقادیر نبوده‌ی files را برای تمرین‌های مفهومی/عملی از فایل config.json سطح ترک بررسی کند یا پر کند.

configlet [global-options] sync [command-options]

Global options:
  -h, --help                   Show this help message and exit
      --version                Show this tool's version information and exit
  -t, --track-dir <dir>        Specify a track directory to use instead of the current directory
  -v, --verbosity <verbosity>  The verbosity of output. Allowed values: q[uiet], n[ormal], d[etailed]

Options for sync:
  -e, --exercise <slug>        Only operate on this exercise
  -p, --prob-specs-dir <dir>   Use this 'problem-specifications' directory, rather than cloning temporarily
  -o, --offline                Do not check that the directory specified by --prob-specs-dir is up to date
  -u, --update                 Prompt to update the seen data that are unsynced
  -y, --yes                    Auto-confirm prompts from --update for updating docs, filepaths, and metadata
      --docs                   Sync Practice Exercise '.docs/introduction.md' and '.docs/instructions.md' files
      --filepaths              Populate empty 'files' values in Concept/Practice exercise '.meta/config.json' files
      --metadata               Sync Practice Exercise '.meta/config.json' metadata values
      --tests [mode]           Sync Practice Exercise '.meta/tests.toml' files.
                               The mode value specifies how missing tests are handled when using --update.
                               Allowed values: c[hoose], i[nclude], e[xclude] (default: choose)

مستندات

تمرین عملی‌ای که از مخزن problem-specifications برگرفته شده است باید فایلی به نام .docs/instructions.md داشته باشد (و احتمالاً فایلی .docs/introduction.md هم) که مستندات آن تمرین را از problem-specifications در خود دارد.

برای بررسی همه‌ی تمرین‌های عملی ترک از نظر به‌روزرسانی‌های موجود در مستندات (و خروج با کد خروج ناصفر در صورت وجود حداقل یک به‌روزرسانی):

configlet sync --docs

برای به‌روزرسانی تعاملی مستندات همه‌ی تمرین‌های عملی، گزینه‌ی --update را اضافه کنید (یا برای کوتاهی -u):

configlet sync --docs --update

برای به‌روزرسانی غیرتعاملی مستندات همه‌ی تمرین‌های عملی، گزینه‌ی --yes را اضافه کنید (یا برای کوتاهی -y):

configlet sync --docs --update --yes

برای کار روی یک تمرین عملی مشخص، از گزینه‌ی --exercise استفاده کنید (یا برای کوتاهی -e). برای نمونه، برای به‌روزرسانی غیرتعاملی مستندات تمرین prime-factors:

configlet sync --docs -uy -e prime-factors

فراداده

هر تمرین در یک ترک باید فایلی به نام .meta/config.json داشته باشد. برای تمرین عملی‌ای که از مخزن problem-specifications برگرفته شده است، این فایل باید جفت‌های کلید/مقدار blurb، source و source_url را که در فایل metadata.toml بالادستی متناظر وجود دارند در خود داشته باشد.

برای بررسی همه‌ی تمرین‌های عملی از نظر به‌روزرسانی‌های موجود در فراداده (و خروج با کد خروج ناصفر در صورت وجود حداقل یک به‌روزرسانی):

configlet sync --metadata

برای به‌روزرسانی تعاملی فراداده‌ی همه‌ی تمرین‌های عملی، گزینه‌ی --update را اضافه کنید (یا برای کوتاهی -u):

configlet sync --metadata --update

برای به‌روزرسانی غیرتعاملی فراداده‌ی همه‌ی تمرین‌های عملی، گزینه‌ی --yes را اضافه کنید (یا برای کوتاهی -y):

configlet sync --metadata --update --yes

برای کار روی یک تمرین عملی مشخص، از گزینه‌ی --exercise استفاده کنید (یا برای کوتاهی -e). برای نمونه، برای به‌روزرسانی غیرتعاملی فراداده‌ی تمرین prime-factors:

configlet sync --metadata -uy -e prime-factors

تست‌ها

اگر ترکی تمرینی را پیاده‌سازی می‌کند که داده‌های تست آن در مخزن problem-specifications وجود دارد، آن تمرین باید فایلی به نام .meta/tests.toml داشته باشد. هدف فایل tests.toml این است که پیگیری کند کدام تست‌ها توسط تمرین پیاده‌سازی شده‌اند. تست‌های این فایل با UUID خودشان مشخص می‌شوند و هر تست یک مقدار از نوع «منطقی» دارد که نشان می‌دهد آن تمرین پیاده‌اش کرده است یا نه.

فایل tests.toml این قالب را دارد:

# This is an auto-generated file.
#
# Regenerating this file via `configlet sync` will:
# - Recreate every `description` key/value pair
# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
# - Preserve any other key/value pair
#
# As user-added comments (using the # character) will be removed when this file
# is regenerated, comments can be added via a `comment` key.
[1e22cceb-c5e4-4562-9afe-aef07ad1eaf4]
description = "basic"
[79ae3889-a5c0-4b01-baf0-232d31180c08]
description = "lowercase words"
[ec7000a7-3931-4a17-890e-33ca2073a548]
description = "invalid input"
include = false
comment = "excluded because we don't want to add error handling to the exercise"

در این حالت، ترک تصمیم گرفته است دو مورد از سه تست موجود را پیاده‌سازی کند. اگر ترکی از تولیدکننده‌ی تست برای ساختن مجموعه‌ی تست یک تمرین استفاده می‌کند، باید از محتوای فایل tests.toml استفاده کند تا تعیین کند کدام تست‌ها را در مجموعه‌ی تست تولیدشده بگنجاند.

برای بررسی فایل tests.toml همه‌ی تمرین‌های عملی از نظر به‌روزرسانی‌های موجود در تست‌ها (و خروج با کد خروج ناصفر اگر حداقل یک مورد تست در داده‌های متعارف تمرین آمده باشد اما در tests.toml نباشد):

configlet sync --tests

برای به‌روزرسانی تعاملی فایل tests.toml همه‌ی تمرین‌های عملی، گزینه‌ی --update را اضافه کنید:

configlet sync --tests --update

برای هر تست نبوده، این ابزار از کاربر می‌پرسد که آن را بگنجاند، حذف کند یا رد کند و فایل tests.toml متناظر را بر همان اساس به‌روزرسانی می‌کند. Configlet فایل tests.toml یک تمرین را وقتی می‌نویسد که کاربر انتخاب‌های خود را برای آن تمرین به پایان رسانده باشد. یعنی می‌توانید configlet را هنگام نمایش یک پرسش خاتمه دهید (برای نمونه، با فشردن Ctrl-C در ترمینال) و حداکثر تصمیم‌های همگام‌سازی مربوط به یک تمرین را از دست بدهید.

برای گنجاندن غیرتعاملی همه‌ی موارد تست دیده‌نشده، از --tests include استفاده کنید. برای نمونه، برای انجام این کار روی تمرینی به نام prime-factors:

configlet sync --tests include -u -e prime-factors

یادتان نرود که این تست‌ها را واقعاً در ترک پیاده‌سازی کنید!

مسیرهای فایل

در پایان، دستور sync به «همگام‌سازی» از منبعی هم می‌پردازد که problem-specifications نیست: فایل config.json سطح ترک. هر تمرین مفهومی و هر تمرین عملی باید فایلی به نام .meta/config.json با یک شیء files داشته باشد که مکان‌های (نسبی) فایل‌هایی را که تمرین به کار می‌برد مشخص می‌کند. چنین مسیرهای فایلی معمولاً از الگویی ساده پیروی می‌کنند و بنابراین configlet می‌تواند مقادیر سطح تمرین را از الگوهای موجود در کلید files فایل config.json سطح ترک پر کند.

برای بررسی اینکه کلید files هر تمرین مفهومی و هر تمرین عملی ترک کاملاً پر شده است (یا حداقل کلیدی است که نمی‌توان آن را از کلید files سطح ترک پر کرد):

configlet sync --filepaths

(توجه کنید که configlet lint هم وقتی کلید files یک تمرین نبوده یا خالی باشد خطا می‌دهد.)

برای پر کردن مقادیر خالی یا نبوده‌ی کلید files سطح تمرین برای همه‌ی تمرین‌های مفهومی و عملی، با استفاده از الگوهای موجود در کلید files سطح ترک:

configlet sync --filepaths --update

برای انجام این کار به‌صورت غیرتعاملی و فقط برای یک تمرین به نام prime-factors:

configlet sync --filepaths -uy -e prime-factors

استفاده از sync هنگام افزودن تمرین جدید به یک ترک

دستور sync هنگام افزودن تمرین جدید به یک ترک به کار می‌آید. اگر در حال افزودن تمرین عملی‌ای به نام foo هستید که در problem-specifications وجود دارد، یک روال کار ممکن چنین است:

1. به‌صورت دستی برای تمرین foo ورودی‌ای به فایل config.json سطح ترک اضافه کنید. این کار تمرین را برای configlet sync قابل مشاهده می‌کند.
2. دستور configlet sync --docs --filepaths --metadata -uy -e foo را اجرا کنید تا مستندات تمرین و یک فایل .meta/config.json اولیه با مقادیر پر شده‌ی files، blurb و شاید source و source_url ساخته شود.
3. فایل .meta/config.json تمرین را هر طور که می‌خواهید ویرایش کنید. برای نمونه، خودتان را به آرایه‌ی authors اضافه کنید.
4. دستور configlet sync --tests include -u -e foo را اجرا کنید تا فایلی .meta/tests.toml با همه‌ی تست‌های گنجانده‌شده ساخته شود.
5. فایل .meta/tests.toml را ببینید و به هر مورد تستی که تمرین پیاده‌سازی نخواهد کرد include = false را اضافه کنید.
6. تست‌های تمرین را طوری پیاده‌سازی کنید که با تست‌های گنجانده‌شده در .meta/tests.toml مطابقت داشته باشند.
7. فایل‌های الزامی دیگر را اضافه کنید.