Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update sync documentation #1799

Merged
merged 8 commits into from
Jun 17, 2021
Merged

Update sync documentation #1799

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5369585
Update sync documentation
ErikSchierboom May 4, 2021
a52af2c
Update README.md
ErikSchierboom May 4, 2021
d9c2c69
README: reflect latest sync changes
ee7 Jun 11, 2021
b316725
README: tweak wording around `tests.toml`
ee7 Jun 11, 2021
0ae5bdc
README: add more docs for `sync`
ee7 Jun 11, 2021
f40ba52
README: show `comment` usage
ee7 Jun 17, 2021
5bcaab7
README: recommend `sync` more strongly
ee7 Jun 17, 2021
3a373d9
Update README.md
ErikSchierboom Jun 17, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 10 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,27 +190,26 @@ If a track implements an exercise for which test data exists, the exercise _must
A `tests.toml` file for a track's `two-fer` exercise looks like this:

```toml
[canonical-tests]
[19709124-b82e-4e86-a722-9e5c5ebf3952]
description = "no name given"

# no name given
"19709124-b82e-4e86-a722-9e5c5ebf3952" = true
[3451eebd-123f-4256-b667-7b109affce32]
description = "a name given"
include = false

# a name given
"3451eebd-123f-4256-b667-7b109affce32" = true

# another name given
"653611c6-be9f-4935-ab42-978e25fe9a10" = false
[653611c6-be9f-4935-ab42-978e25fe9a10]
description = "another name given"
```

In this case, the track has chosen to implement two of the three available tests.
In this case, the track has chosen to implement two of the three available tests (`include = true` is the default and is omitted).

If a track uses a _test generator_ to generate an exercise's test suite, it _must_ use the contents of the `tests.toml` file to determine which tests to include in the generated test suite.

### Track Test Data Tooling

To make it easy to keep the `tests.toml` up to date, tracks can use the [`canonical_data_syncer` application](https://github.com/exercism/canonical-data-syncer). This application is a small, standalone binary that will compare the tests specified in the `tests.toml` files against the tests that are defined in the exercise's canonical data. It then interactively gives the maintainer the option to include or exclude test cases that are currently missing, updating the `tests.toml` file accordingly.
To make it easy to keep the `tests.toml` up to date, tracks can use the [`configlet` application](https://github.com/exercism/configlet)'s `sync` command. This command will compare the tests specified in the `tests.toml` files against the tests that are defined in the exercise's canonical data. It then interactively gives the maintainer the option to include or exclude test cases that are currently missing, updating the `tests.toml` file accordingly.

To use the canonical data syncer tool, tracks should copying the [`fetch-canonical_data_syncer`](https://github.com/exercism/canonical-data-syncer/blob/main/scripts/fetch-canonical_data_syncer) and/or [`fetch-canonical_data_syncer.ps1`](https://github.com/exercism/canonical-data-syncer/blob/main/scripts/fetch-canonical_data_syncer.ps1) scripts into their repository. Then, running either of these scripts will download the latest version of the tool to the track's `bin` directory. The tool can be run using `./bin/canonical_data_syncer` or `.\bin\canonical_data_syncer.exe`, depending on your operating system.
To use the configlet tool, tracks should copy the [`fetch-configlet`](https://github.com/exercism/configlet/blob/main/scripts/fetch-configlet) and/or [`fetch-configlet.ps1`](https://github.com/exercism/configlet/blob/main/scripts/fetch-configlet.ps1) scripts into their repository's `bin` directory. Then, running either of these scripts will download the latest version of the tool to the same `bin` directory. The tool can then be run using `./bin/configlet sync` or `.\bin\configlet.exe sync`, depending on your operating system.

## Conventions

Expand Down