From 5b4989933b1b64a02eaf02d2ee0feeb2968b65c5 Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Thu, 15 Aug 2024 14:34:52 +0200 Subject: [PATCH] Document workflows (#561) --- building/config.json | 90 +++++++++++-------- building/tracks/README.md | 2 +- building/tracks/ci/workflows.md | 20 +++-- building/tracks/ci/workflows/configlet.md | 7 +- building/tracks/ci/workflows/deploy.md | 12 +++ .../workflows/no-important-files-changed.md | 13 +++ .../pause-community-contributions.md | 18 ++++ building/tracks/ci/workflows/sync-labels.md | 8 +- 8 files changed, 121 insertions(+), 49 deletions(-) create mode 100644 building/tracks/ci/workflows/deploy.md create mode 100644 building/tracks/ci/workflows/no-important-files-changed.md create mode 100644 building/tracks/ci/workflows/pause-community-contributions.md diff --git a/building/config.json b/building/config.json index b19ba555..1784fece 100644 --- a/building/config.json +++ b/building/config.json @@ -673,6 +673,24 @@ "path": "building/tracks/ci/workflows/configlet.md", "title": "configlet workflow" }, + { + "uuid": "d7e3f615-3796-43a5-a4a2-632200a8cd47", + "slug": "tracks/ci/workflows/deploy", + "path": "building/tracks/ci/workflows/deploy.md", + "title": "Deploy workflow" + }, + { + "uuid": "3a3bea49-9bc0-444c-a95d-93ecc8b0659e", + "slug": "tracks/ci/workflows/no-important-files-changed", + "path": "building/tracks/ci/workflows/no-important-files-changed.md", + "title": "No important files changed workflow" + }, + { + "uuid": "b93743e9-4069-46f6-83e9-f873ab8c80c3", + "slug": "tracks/ci/workflows/pause-community-contributions", + "path": "building/tracks/ci/workflows/pause-community-contributions.md", + "title": "Pause community contributions workflow" + }, { "uuid": "fd512058-4525-4e14-a912-9df870025989", "slug": "tracks/ci/workflows/sync-labels", @@ -685,42 +703,6 @@ "path": "building/tracks/ci/migrating-from-travis.md", "title": "Migrating from Travis" }, - { - "uuid": "40e765ac-3fd1-4c17-8236-7a6e718cfe64", - "slug": "markdown", - "path": "building/markdown/README.md", - "title": "Markdown", - "blurb": "" - }, - { - "uuid": "dd132018-e53d-4347-a30d-aadfe6c1743b", - "slug": "markdown/internal-linking", - "path": "building/markdown/internal-linking.md", - "title": "Internal Linking", - "blurb": "" - }, - { - "uuid": "2ce5a5bf-229f-4757-9ae0-d6826494dbbf", - "slug": "markdown/markdown", - "path": "building/markdown/markdown.md", - "title": "Markdown Specification", - "blurb": "" - }, - { - "uuid": "b2f8687f-77e1-4044-a964-35fd2bd3f1b3", - "slug": "markdown/style-guide", - "path": "building/markdown/style-guide.md", - "title": "Exercism's Style Guide", - "blurb": "" - }, - { - "uuid": "d34ced45-63ff-41c7-967d-3ac72e1b5d8e", - "slug": "markdown/widgets", - "path": "building/markdown/widgets.md", - "title": "Widgets", - "blurb": "" - }, - { "uuid": "00b76de0-1e0e-47d0-b293-950d12b1a4c0", "slug": "tooling", @@ -889,6 +871,42 @@ "title": "Test Generators", "blurb": "" }, + + { + "uuid": "40e765ac-3fd1-4c17-8236-7a6e718cfe64", + "slug": "markdown", + "path": "building/markdown/README.md", + "title": "Markdown", + "blurb": "" + }, + { + "uuid": "dd132018-e53d-4347-a30d-aadfe6c1743b", + "slug": "markdown/internal-linking", + "path": "building/markdown/internal-linking.md", + "title": "Internal Linking", + "blurb": "" + }, + { + "uuid": "2ce5a5bf-229f-4757-9ae0-d6826494dbbf", + "slug": "markdown/markdown", + "path": "building/markdown/markdown.md", + "title": "Markdown Specification", + "blurb": "" + }, + { + "uuid": "b2f8687f-77e1-4044-a964-35fd2bd3f1b3", + "slug": "markdown/style-guide", + "path": "building/markdown/style-guide.md", + "title": "Exercism's Style Guide", + "blurb": "" + }, + { + "uuid": "d34ced45-63ff-41c7-967d-3ac72e1b5d8e", + "slug": "markdown/widgets", + "path": "building/markdown/widgets.md", + "title": "Widgets", + "blurb": "" + }, { "uuid": "3423667a-3b30-4590-9a88-5a30f712f382", "slug": "product", diff --git a/building/tracks/README.md b/building/tracks/README.md index ac2d64fc..61735c16 100644 --- a/building/tracks/README.md +++ b/building/tracks/README.md @@ -102,7 +102,7 @@ csharp ### Avoiding triggering unnecessary test runs -When you merge a track PR that touches an exercise, it triggers the latest published iteration of students' solutions to be re-tested. +When you merge a track PR that touches an exercise, it triggers _all_ the latest published iteration of students' solutions to be re-tested. For popular exercises, this is a _very_ expensive operation (70,000 test runs for Python Hello World as an extreme!). **We encourage you to try and avoid doing this unnecessarily.** diff --git a/building/tracks/ci/workflows.md b/building/tracks/ci/workflows.md index 772bef4c..f79e5639 100644 --- a/building/tracks/ci/workflows.md +++ b/building/tracks/ci/workflows.md @@ -23,23 +23,29 @@ You should thus not manually change their contents. ### General workflows -- [`sync-labels.yml`](/docs/building/tracks/ci/workflows/sync-labels): automatically syncs the repository's labels from a `labels.yml` file +- [Sync labels](/docs/building/tracks/ci/workflows/sync-labels): sync the repository's labels from file ### Track-specific workflows -- [`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 +- [configlet](/docs/building/tracks/ci/workflows/configlet): checks if the track's (configuration) files are properly structured - both syntactically and semantically +- [No important files changed](/docs/building/tracks/ci/workflows/no-important-files-changed): comments on pull requests that would cause re-testing of existing solutions +- [Test](/docs/building/tracks/new/setup-continuous-integration#h-test-workflow): verify the track's exercises ### Tooling-specific workflows -- `deploy.yml`: deploy the tooling Docker image to Docker Hub and ECR +- [Deploy](/docs/building/tracks/ci/workflows/deploy): deploy the track tooling Docker image to Docker Hub and ECR + +### Optional workflows + +There are also some workflows that tracks might opt-into: + +- [Pause community contributions](/docs/building/tracks/ci/workflows/pause-community-contributions): auto-comment on newly issues and PRs created by users who are not member of the Exercism GitHub organisation ## Custom workflows Maintainers are free to add custom workflows to their repos. Examples of such workflows could be: -- Linting of shell scripts ([example](https://github.com/exercism/configlet/blob/3baa09608c8ac327315c887608c13a68ae8ac359/.github/workflows/shellcheck.yml)) -- Auto-commenting on pull requests ([example](https://github.com/exercism/elixir/blob/b737f80cc93fcfdec6c53acb7361819834782470/.github/workflows/pr-comment.yml)) +- [Linting of shell scripts](https://github.com/exercism/configlet/blob/3baa09608c8ac327315c887608c13a68ae8ac359/.github/workflows/shellcheck.yml) +- [Auto-commenting on pull requests](https://github.com/exercism/elixir/blob/b737f80cc93fcfdec6c53acb7361819834782470/.github/workflows/pr-comment.yml) - Etc. diff --git a/building/tracks/ci/workflows/configlet.md b/building/tracks/ci/workflows/configlet.md index dca0813e..2e1a8910 100644 --- a/building/tracks/ci/workflows/configlet.md +++ b/building/tracks/ci/workflows/configlet.md @@ -1,7 +1,6 @@ # 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. +The configlet 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 @@ -30,3 +29,7 @@ fmt = true ``` 3. Once this PR is merged, the `configlet` workflow will also verify the track's configuration files' formatting. + +## Source + +The workflow is defined in the `.github/workflows/configlet.yml` file. diff --git a/building/tracks/ci/workflows/deploy.md b/building/tracks/ci/workflows/deploy.md new file mode 100644 index 00000000..8b5da98f --- /dev/null +++ b/building/tracks/ci/workflows/deploy.md @@ -0,0 +1,12 @@ +# Deploy workflow + +The deploy workflow is used to deploy [track tooling](/docs/building/tooling) to: + +1. [Docker Hub](https://hub.docker.com/): used in scripts or for local testing. + Publicly available. +2. [ECR](https://aws.amazon.com/ecr/): used in the production environment to test submitted solutions. + Private. + +## Source + +The workflow is defined in the `.github/workflows/deploy.yml` file. diff --git a/building/tracks/ci/workflows/no-important-files-changed.md b/building/tracks/ci/workflows/no-important-files-changed.md new file mode 100644 index 00000000..f44589e5 --- /dev/null +++ b/building/tracks/ci/workflows/no-important-files-changed.md @@ -0,0 +1,13 @@ +# No important files changed workflow + +When a track PR is merged that touches an exercise, it triggers _all_ the latest published iteration of students' solutions to be re-tested. +For popular exercises, this is a _very_ expensive operation (70,000 test runs for Python Hello World as an extreme!). + +This workflow checks if the changes in a PR would trigger the re-testing of solutions, and if so, it adds a comment explaining the risk of merging the PR _as is_. +It also explains how to merge the PR without re-testing solutions. + +For more information, check the [Avoiding triggering unnecessary test runs](https://exercism.org/docs/building/tracks#h-avoiding-triggering-unnecessary-test-runs) documentation. + +## Source + +The workflow is defined in the `.github/workflows/no-important-files-changed.yml` file. diff --git a/building/tracks/ci/workflows/pause-community-contributions.md b/building/tracks/ci/workflows/pause-community-contributions.md new file mode 100644 index 00000000..4b2ec6b4 --- /dev/null +++ b/building/tracks/ci/workflows/pause-community-contributions.md @@ -0,0 +1,18 @@ +# Pause community contributions + +Some repositories don't have the resources to triage/review issues or pull requests from non-maintainer users. +The pause community solutions +If a repository has enabled this workflow, it will automatically comment on a newly opened issue or pull request if the author is _not_ member of Exercism's GitHub organisation. +The comment will suggest the user to first open a topic on the Exercism forum. + +## Enabling the workflow + +Add the [.github/workflows/pause-community-contributions.yml file](https://github.com/exercism/github-actions/blob/b5424c17f661f5529493258a1ad480013351aa9e/.github/workflows/pause-community-contributions.yml) into your repository. + +## Disabling the workflow + +Remove the workflow file from your repository. + +## Source + +The workflow is defined in the `.github/workflows/pause-community-contributions.yml` file. diff --git a/building/tracks/ci/workflows/sync-labels.md b/building/tracks/ci/workflows/sync-labels.md index 1c3f501c..b697c2c9 100644 --- a/building/tracks/ci/workflows/sync-labels.md +++ b/building/tracks/ci/workflows/sync-labels.md @@ -1,8 +1,6 @@ # Sync labels workflow -The sync labels workflow is defined in the `.github/workflows/sync-labels.yml` file. -The goal of this workflow is to add/update/delete the repository's [GitHub labels](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels). -The labels themselves are defined in the `.github/labels.yml` file. +The sync labels workflow synchronizes a repository's [GitHub labels](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels) with the contents of the `.github/labels.yml` file. Whenever the `.github/labels.yml` file changes, the sync labels workflow will automatically update the repository's labels. ## Customizing labels @@ -19,3 +17,7 @@ After merging that PR, the labels will be automatically updated (see description ```exercism/caution Never manually edit the `.github/labels.yml` file, as those changes will be overwritten the next time labels are synced. ``` + +## Source + +The workflow is defined in the `.github/workflows/sync-labels.yml` file.