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.
• رمز الخروج يكون 0 عندما تكون كل البيانات المرئية متزامنة عند خروج configlet، و1 بخلاف ذلك.

لاحظ أنه في إصدارات 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. أضف يدويًا مدخلًا إلى ملف config.json على مستوى المسار للتمرين foo. هذا يجعل التمرين مرئيًا لـ 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. أضف الملفات المطلوبة الأخرى.