configlet sync

problem-specifications 저장소와 연습 문제 데이터 동기화하기

Exercism 트랙의 실습 문제는 exercism/problem-specifications 저장소에 있는 명세를 바탕으로 구현하는 경우가 많아요.

Exercism은 모든 연습 문제가 특정 파일(예: .docs/instructions.md)의 사본을 각자 가지고 있을 것을 의도적으로 요구해요. 그 연습 문제가 이미 problem-specifications에 있어도 마찬가지예요. 그래서 configlet에는 sync 명령이 있어요. 이 명령으로 트랙의 실습 문제가 그 상위 원본과 동기화되어 있는지 확인하고, 업데이트가 있으면 갱신할 수 있어요.

problem-specifications에서 업데이트할 수 있는 데이터에는 문서, 메타데이터, 테스트 세 가지가 있어요. 그리고 트랙 수준 config.json 파일에서 채울 수 있는 데이터가 한 가지 더 있는데, 바로 연습 문제 config 파일의 파일 경로예요.

이런 데이터 종류를 확인하고 업데이트하는 방법은 아래 각 절에서 설명하지만, 먼저 간단히 요약해 볼게요.

  • 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는 명세에 없는 키를 제거해요. 사용자 정의 키/값 쌍은 여전히 지원되는데, 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 저장소에서 파생된 실습 문제에는 problem-specifications의 연습 문제 문서를 담은 .docs/instructions.md 파일이 있어야 해요(그리고 .docs/introduction.md 파일도 있을 수 있어요).

트랙의 모든 실습 문제에 사용할 수 있는 문서 업데이트가 있는지 확인하려면(업데이트가 하나라도 있으면 0이 아닌 종료 코드로 종료해요):

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 키/값 쌍이 들어 있어야 해요.

모든 실습 문제에 사용할 수 있는 메타데이터 업데이트가 있는지 확인하려면(업데이트가 하나라도 있으면 0이 아닌 종료 코드로 종료해요):

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에는 없는 테스트 케이스가 하나라도 있으면 0이 아닌 종료 코드로 종료해요):

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 파일로부터의 "동기화"도 처리해요. 모든 개념 문제와 실습 문제에는 연습 문제가 사용하는 파일의 (상대) 위치를 지정하는 files 객체가 담긴 .meta/config.json 파일이 있어야 해요. 이런 파일 경로는 보통 단순한 패턴을 따르기 때문에, configlet은 트랙 수준 config.json 파일의 files 키에 있는 패턴으로 연습 문제 수준의 값을 채울 수 있어요.

트랙의 모든 개념 문제와 실습 문제에 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 명령은 트랙에 새 연습 문제를 추가할 때 유용해요. problem-specifications에 있는 foo라는 실습 문제를 추가한다면, 가능한 작업 흐름은 다음과 같아요:

  1. 트랙 수준 config.json 파일에 foo 연습 문제 항목을 직접 추가해요. 그러면 configlet sync가 그 연습 문제를 인식할 수 있어요.
  2. configlet sync --docs --filepaths --metadata -uy -e foo를 실행해서 연습 문제의 문서와, files, blurb, 그리고 어쩌면 source, source_url 값이 채워진 시작용 .meta/config.json 파일을 만들어요.
  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. 나머지 필수 파일을 추가해요.