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 রিপো থেকে নেওয়া একটি প্র্যাকটিস অনুশীলনীর জন্য, এই ফাইলে সংশ্লিষ্ট আপস্ট্রিম metadata.toml ফাইলে থাকা blurb, source ও source_url কী/ভ্যালু জোড়া থাকা উচিত।

প্রতিটি প্র্যাকটিস অনুশীলনীতে মেটাডেটার কোনো আপডেট পাওয়া যায় কি না তা যাচাই করতে (অন্তত একটি আপডেট পাওয়া গেলে নন-জিরো এক্সিট কোড নিয়ে বেরিয়ে যাবে):

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 কমান্ডটি কাজে লাগে। problem-specifications-এ থাকা foo নামের একটি প্র্যাকটিস অনুশীলনী যদি আপনি যোগ করেন, তাহলে একটি সম্ভাব্য কর্মপ্রবাহ হলো:

1. ট্র্যাক-লেভেলের config.json ফাইলে হাতে foo অনুশীলনীর জন্য একটি এন্ট্রি যোগ করুন। এতে অনুশীলনীটি configlet sync-এর কাছে দৃশ্যমান হয়।
2. অনুশীলনীর ডকুমেন্টেশন এবং পূরণ করা files, blurb ও সম্ভবত source এবং source_url মানসহ একটি প্রাথমিক .meta/config.json ফাইল তৈরি করতে configlet sync --docs --filepaths --metadata -uy -e foo রান করুন।
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. বাকি প্রয়োজনীয় ফাইলগুলো যোগ করুন।