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 कमांड इस्तेमाल कीजिए। हालाँकि, जब ज़रूरी की (authors, files, blurb) गायब हों, तो configlet sync उन्हें जोड़ता ज़रूर है (वे खाली भी हो सकती हैं)। यह कम "सिंक जैसा" है, लेकिन ज़्यादा सुविधाजनक है: नया अभ्यास बनाते समय आप sync की मदद से एक शुरुआती .meta/config.json फाइल बना सकते हैं।
• configlet sync उन की को हटा देता है जो स्पेक में नहीं हैं। कस्टम की/वैल्यू जोड़े अब भी समर्थित हैं: उन्हें custom नाम के JSON ऑब्जेक्ट के अंदर लिखा जाना चाहिए।
• जब configlet बंद होता है, तब अगर सारा देखा गया डेटा सिंक में हो, तो एग्ज़िट कोड 0 होता है, वरना 1।

ध्यान दीजिए कि configlet के रिलीज़ 4.0.0-alpha.34 और उससे पहले के संस्करणों में, sync कमांड सिर्फ टेस्ट पर काम करता था।

उपयोग

sync कमांड की मदद से 'problem-specifications' से प्रैक्टिस अभ्यास के डॉक्स, मेटाडेटा और टेस्ट जाँचे या अपडेट किए जा सकते हैं। यह ट्रैक के 'config.json' से कॉन्सेप्ट/प्रैक्टिस अभ्यासों की गायब files वैल्यू भी जाँच सकता है या भर सकता है।

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 ट्रैक-लेवल config.json फाइल की files की में दिए पैटर्न से अभ्यास-लेवल की वैल्यू भर सकता है।

यह जाँचने के लिए कि ट्रैक के हर कॉन्सेप्ट अभ्यास और प्रैक्टिस अभ्यास की files की पूरी तरह भरी हुई है (या कम से कम ऐसी है जिसे ट्रैक-लेवल files की से नहीं भरा जा सकता):

configlet sync --filepaths

(ध्यान दीजिए कि जब किसी अभ्यास की files की गायब या खाली हो, तो configlet lint भी एक एरर देगी।)

ट्रैक-लेवल 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. हर टेस्ट को शामिल करते हुए एक .meta/tests.toml फाइल बनाने के लिए configlet sync --tests include -u -e foo चलाइए।
5. उस .meta/tests.toml फाइल को देखिए, और हर उस टेस्ट केस में include = false जोड़िए जिसे अभ्यास लागू नहीं करेगा।
6. अभ्यास के लिए टेस्ट ऐसे लागू कीजिए जो .meta/tests.toml में शामिल टेस्ट से मेल खाएँ।
7. बाकी ज़रूरी फाइलें जोड़िए।