add document for the update-checks-doc script

Author: rhysd

CONTRIBUTING.md

@@ -5,7 +5,7 @@ To report a bug, please submit a new ticket on GitHub. It's helpful to search si
 https://github.com/rhysd/actionlint/issues/new
 
 Providing a reproducible workflow content is much appreciated. If only a small snippet of workflow is provided or no
-input is provided at all, such issue tickets may get lower priority since they are occasionally time consuming to
+input is provided at all, such issue tickets may get lower priority because they are occasionally time consuming to
 investigate.
 
 # Sending a patch
@@ -21,6 +21,10 @@ Before submitting your PR, please ensure the following points:
 - Confirm build/tests/lints passed. How to run them is described in the following sections.
 - If you added a new feature, consider to add tests and explain it in [the usage document](docs/usage.md).
 - If you added a new public API, consider to add tests and a doc comment for the API.
+- If you updated [the checks document](docs/checks.md), ensure to run [the maintenance script](#about-checks-doc).
+
+Special thanks to the native English speakers for proofreading the documentation and error messages, as the author is not
+proficient in English.
 
 # Development
 
@@ -219,3 +223,14 @@ All tests are automated.
   - `testdata/projects/` contains 'Project' tests. Each directories represent a single project (meaning a repository on GitHub).
     Corresponding `*.out` files are expected error messages. Empty `*.out` file means the test case should cause no errors.
     'Project' test is used for use cases where multiple files are related (reusable workflows, local actions, config files, ...).
+
+<a id="about-checks-doc"></a>
+## How to write checks document
+
+The ['Checks' document](./docs/checks.md) is a large document to explain all checks by actionlint.
+
+This document is maintained with [`update-checks-doc`](./scripts/update-checks-doc) script. This script automatically updates
+the code blocks after `Output:` and the `Playground` links. This script should be run after modifying the document.
+
+Please see [the readme of the script](./scripts/update-checks-doc/README.md) for the usage and knowing the details of the
+document format that this script assumes.

scripts/update-checks-doc/README.md

@@ -0,0 +1,68 @@
+update-checks-doc
+=================
+
+This is a script to maintain [the 'Checks' document](../../docs/checks.md).
+
+This script does:
+
+- update the outputs of the example inputs; the code blocks after `Output:` header
+- update the links to the [playground](https://rhysd.github.io/actionlint/) for the example inputs
+
+For making the implementation simple, this script does not support Windows. Please run this script
+on Linux or macOS.
+
+## Usage
+
+Update the document. This command directly modifies the file.
+
+```sh
+go run ./scripts/update-checks-doc ./docs/checks.md
+```
+
+Check the document is up-to-date.
+
+```sh
+go run ./scripts/update-checks-doc -check ./docs/checks.md
+```
+
+The check is run on the [CI workflow](../../.github/workflows/ci.yaml).
+
+## Format
+
+The format of the check document is:
+
+````markdown
+<a id="some-id"></a>
+## This is title of the check
+
+Example input:
+
+```yaml
+This section is referred to generate the output and the playground link
+```
+
+Output:
+
+```
+This section will be auto-generated
+```
+
+[Playground](https://rhysd.github.io/actionlint/#THIS_HASH_PART_WILL_BE_AUTO_GENERATED)
+
+Explanation for the check...
+````
+
+When you don't want to update the output by this script, put the comment as follows. This script
+will ignore the code block. Instead you need to write the output in the code blcok manually.
+
+```yaml
+Output:
+<!-- Skip update output -->
+```
+
+When you don't want to put a playground link for your example input, put the comment as follows
+instead of the link. This script will not generate the hash for the playground link.
+
+```yaml
+<!-- Skip playground link -->
+```