Document workflows (#561)

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",

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.**

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.

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.

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.

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.

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.

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.