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命令很有用。 如果你要添加一个名为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. 添加其他必需的文件。