diff --git a/building/config.json b/building/config.json index 2a7de427..85726175 100644 --- a/building/config.json +++ b/building/config.json @@ -667,6 +667,12 @@ "path": "building/tracks/ci/workflows.md", "title": "Workflows" }, + { + "uuid": "753dfe68-af5f-466e-b9a1-5797b6088ab0", + "slug": "tracks/ci/workflows/configlet", + "path": "building/tracks/ci/workflows/configlet.md", + "title": "configlet workflow" + }, { "uuid": "191b0fa1-96e2-48a6-ad2e-c34f57443799", "slug": "tracks/ci/migrating-from-travis", diff --git a/building/configlet/README.md b/building/configlet/README.md index 03ba944c..bf295621 100644 --- a/building/configlet/README.md +++ b/building/configlet/README.md @@ -51,7 +51,13 @@ How to generate UUIDs can be found [here](/docs/building/configlet/uuid). ## Formatting Configlet has a `fmt` command to help with consistent formatting of the JSON files in the track repo. -The `fmt` command currently only operates on the exercise `.meta/config.json` files but it is likely to operate on all the track JSON files in the future. +The `fmt` command formats the following files: + +- `config.json` +- `exercises/{concept,practice}/*/.approaches/config.json` +- `exercises/{concept,practice}/*/.articles/config.json` +- `exercises/{concept,practice}/*/.meta/config.json` + You can learn more about the format command [here](/docs/building/configlet/format). ## Installation diff --git a/building/configlet/format.md b/building/configlet/format.md index d9f444d5..a939becf 100644 --- a/building/configlet/format.md +++ b/building/configlet/format.md @@ -3,14 +3,17 @@ An Exercism track repo has many JSON files, including: - The track `config.json` file. - - For each concept, a `.meta/config.json` and `links.json` file. - - For each Concept Exercise or Practice Exercise, a `.meta/config.json` file. These files are more readable if they have a consistent formatting Exercism-wide, and so configlet has a `fmt` command for rewriting a track's JSON files in a canonical form. -The `fmt` command currently operates on the exercise `.meta/config.json` files and the track `config.json` file, but it is likely to operate on all the track JSON files in the future. +The `fmt` command formats the following files: + +- `config.json` +- `exercises/{concept,practice}/*/.approaches/config.json` +- `exercises/{concept,practice}/*/.articles/config.json` +- `exercises/{concept,practice}/*/.meta/config.json` ## Usage diff --git a/building/tracks/ci/workflows.md b/building/tracks/ci/workflows.md index 93c4d68e..4e81eebd 100644 --- a/building/tracks/ci/workflows.md +++ b/building/tracks/ci/workflows.md @@ -15,7 +15,11 @@ For information on workflows, check the following docs: ## Shared workflows Some workflows are shared across repositories. -These workflows _should not be changed_. + +```exercism/caution +The shared workflows are automatically synced (from the [org-wide-files repo](https://github.com/exercism/org-wide-files/)). +You should thus not manually change their contents. +``` ### General workflows @@ -23,7 +27,7 @@ These workflows _should not be changed_. ### Track-specific workflows -- `configlet.yml`: runs the [configlet tool](/docs/building/configlet), which checks if a track's (configuration) files are properly structured - both syntactically and semantically +- [`configlet.yml`](/docs/building/tracks/ci/workflows/configlet): runs the [configlet tool](/docs/building/configlet), which checks if a track's (configuration) files are properly structured - both syntactically and semantically - `no-important-files-changed.yml`: checks if pull requests would cause all existing solutions of one or more changes exercises to be re-run - `test.yml`: verify the track's exercises diff --git a/building/tracks/ci/workflows/configlet.md b/building/tracks/ci/workflows/configlet.md new file mode 100644 index 00000000..dca0813e --- /dev/null +++ b/building/tracks/ci/workflows/configlet.md @@ -0,0 +1,32 @@ +# configlet workflow + +The `configlet` workflow is defined in the `.github/workflows/configlet.yml` file. +It uses the [configlet tool](/docs/building/configlet) to check if a track's (configuration) files are properly structured - both syntactically and semantically. +It does this by running [`configlet lint`](/docs/building/configlet/lint). + +## Enable checking file formatting + +Tracks can use [`configlet fmt`](/docs/building/configlet/format) to format the track's various configuration files. +The same command can also be used to check if all configuration files are formatted correctly. + +The `configlet` workflow supports verifying whether the configuration files are formatted correctly, but this is optional and disabled by default. +To opt-into verifying configuration files' formatting, follow these steps: + +1. Create a `.github/org-wide-files-config.toml` file with the following contents + +```toml +[configlet] +fmt = true +``` + +2. After this file is merged into `main`, a PR will automatically be opened that modifies the `configlet.yml` workflow as follows: + +```diff + jobs: + configlet: + uses: exercism/github-actions/.github/workflows/configlet.yml@main ++ with: ++ fmt: true +``` + +3. Once this PR is merged, the `configlet` workflow will also verify the track's configuration files' formatting. diff --git a/building/tracks/new/add-first-exercise.md b/building/tracks/new/add-first-exercise.md index 00a61935..d7c28f12 100644 --- a/building/tracks/new/add-first-exercise.md +++ b/building/tracks/new/add-first-exercise.md @@ -113,5 +113,35 @@ Tip: just can copy-paste-modify the example solution. Once you're done with the exercise, please add your your GitHub username to the `"authors"` array in the exercise's `.meta/config.json` file. This will ensure we correctly credit you with having created the exercise. +### Linting + +To verify that the exercise is setup correctly, you can use the [configlet tool](/docs/building/configlet)'s built-in linting functionality. + +The first step is to fetch the `configlet` tool, for which we've created two scripts: + +- `bin/fetch-configlet`: run this when using \*nix or macOS +- `bin/fetch-configlet.ps1`: run this when using Windows + +Running one of these scripts from the root directory of the track's repo will download the `bin/configlet` respectively `bin/configlet.exe` binary. + +You can then check the exercise for correctness by running [`bin/configlet lint`](/docs/building/configlet/lint). + +````exercism/note +It is likely that `configlet` will report the following error: +```shell +The `tags` array is empty: +/path/to/track/config.json +``` + +This error will be fixed in the [Prepare for launch](/docs/building/tracks/new/prepare-for-launch#h-update-metadata) step, so either: + +- ignore the error (for now), or +- fix the error by adding tags +```` + +```exercism/note +The [`configlet` workflow](/docs/building/tracks/ci/workflows/configlet) will automatically runs `configlet lint` whenever something is pushed to `main` or to a pull request. +``` + [configlet]: /docs/building/configlet [canonical-data.json]: https://github.com/exercism/problem-specifications/blob/main/exercises/hello-world/canonical-data.json diff --git a/building/tracks/new/setup-continuous-integration.md b/building/tracks/new/setup-continuous-integration.md index 469dbbcf..a3055bae 100644 --- a/building/tracks/new/setup-continuous-integration.md +++ b/building/tracks/new/setup-continuous-integration.md @@ -8,10 +8,14 @@ Exercism repos (including track repos) use [GitHub Actions](https://docs.github. GitHub Actions are based on _workflows_, which define scripts to run automatically whenever a specific event occurs (e.g. pushing a commit). For more information on GitHub Actions workflows, check the [workflows docs](/docs/building/tracks/ci/workflows). +## Pre-installed workflows + +Tracks come pre-installed with a number of workflows, most of which you should _not_ modify (they're called _shared workflows_). +There is one workflow that you _should_ change though, which is the `test.yml` workflow. + ## Test workflow -Each track comes with a `test.yml` workflow. -The goal of this workflow is to verify that the track's exercises are in proper shape. +The goal of the `test.yml` workflow is to verify that the track's exercises are in proper shape. The workflow is setup to run automatically (in GitHub Actions terminology: is _triggered_) when a push is made to the `main` branch or to a pull request's branch. The workflow itself should not do much, except for: