From 05d86237d578f3e802b5bdc3f1a94eb43fb9cd11 Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 20 Jun 2025 19:29:22 -0700 Subject: [PATCH 1/3] Document parameter environment variables in task descriptions Tasks are provided to perform common project development and maintenance operations. Some of these tasks are configured by setting an environment variable from the invocation. It will be important for the contributor to be aware of these variables when using the task directly (as opposed to via the "umbrella" convenience functions which set the variables as appropriate for the project). Previously, when done at all, the variables where documented in comments in the taskfile. The contributor would only see that information if they looked at the source content of the taskfile, but a contributor would only be expected to do that if they were working on the taskfile source. The documented way for a contributor to learn about the available tasks is by running the `task --list` command. This displays the contents of the task's `desc` field. So the parameter variables must be documented in that field. --- Taskfile.yml | 35 +++++++++++-------- .../assets/check-npm-task/Taskfile.yml | 7 ++-- .../assets/check-shell-task/Taskfile.yml | 21 ++++++----- .../assets/npm-task/Taskfile.yml | 7 ++-- 4 files changed, 40 insertions(+), 30 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 118843bf..f61f5dbc 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -730,11 +730,12 @@ tasks: -s "{{.SCHEMA_PATH}}" \ -d "{{.DATA_PATH}}" - # Parameter variables: - # - PROJECT_PATH: path of the npm-managed project. Default value: "./" # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/npm-task/Taskfile.yml npm:install-deps: - desc: Install dependencies managed by npm + desc: | + Install dependencies managed by npm. + Environment variable parameters: + - PROJECT_PATH: Path of the npm-managed project (default: "./"). run: when_changed dir: | "{{default "./" .PROJECT_PATH}}" @@ -756,11 +757,12 @@ tasks: --location project \ fix - # Parameter variables: - # - PROJECT_PATH: path of the npm-managed project. Default value: "./" # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-npm-task/Taskfile.yml npm:validate: - desc: Validate npm configuration files against their JSON schema + desc: | + Validate npm configuration files against their JSON schema. + Environment variable parameters: + - PROJECT_PATH: Path of the npm-managed project (default: "./"). deps: - task: npm:install-deps vars: @@ -956,11 +958,12 @@ tasks: cmds: - poetry run pytest workflow-templates/assets/deploy-mkdocs-versioned/siteversion/tests - # Parameter variables: - # - SCRIPT_PATH: path of the script to be checked. # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml shell:check: - desc: Check for problems with shell scripts + desc: | + Check for problems with shell scripts. + Environment variable parameters: + - SCRIPT_PATH: path of the script to be checked. cmds: - | if [[ "{{.SCRIPT_PATH}}" == "" ]]; then @@ -979,11 +982,12 @@ tasks: --format={{default "tty" .SHELLCHECK_FORMAT}} \ "{{.SCRIPT_PATH}}" - # Parameter variables: - # - SCRIPT_PATH: path of the script to be checked. # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml shell:check-mode: - desc: Check for non-executable shell scripts + desc: | + Check for non-executable shell scripts. + Environment variable parameters: + - SCRIPT_PATH: path of the script to be checked. cmds: - | if [[ "{{.SCRIPT_PATH}}" == "" ]]; then @@ -994,11 +998,12 @@ tasks: - | test -x "{{.SCRIPT_PATH}}" - # Parameter variables: - # - SCRIPT_PATH: path of the script to be formatted. # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml shell:format: - desc: Format shell script files + desc: | + Format shell script files. + Environment variable parameters: + - SCRIPT_PATH: path of the script to be formatted. cmds: - | if [[ "{{.SCRIPT_PATH}}" == "" ]]; then diff --git a/workflow-templates/assets/check-npm-task/Taskfile.yml b/workflow-templates/assets/check-npm-task/Taskfile.yml index 4ee014b4..502bfb12 100644 --- a/workflow-templates/assets/check-npm-task/Taskfile.yml +++ b/workflow-templates/assets/check-npm-task/Taskfile.yml @@ -17,11 +17,12 @@ tasks: --location project \ fix - # Parameter variables: - # - PROJECT_PATH: path of the npm-managed project. Default value: "./" # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-npm-task/Taskfile.yml npm:validate: - desc: Validate npm configuration files against their JSON schema + desc: | + Validate npm configuration files against their JSON schema. + Environment variable parameters: + - PROJECT_PATH: Path of the npm-managed project (default: "./"). deps: - task: npm:install-deps vars: diff --git a/workflow-templates/assets/check-shell-task/Taskfile.yml b/workflow-templates/assets/check-shell-task/Taskfile.yml index 1e009c2e..6998e50d 100644 --- a/workflow-templates/assets/check-shell-task/Taskfile.yml +++ b/workflow-templates/assets/check-shell-task/Taskfile.yml @@ -2,11 +2,12 @@ version: "3" tasks: - # Parameter variables: - # - SCRIPT_PATH: path of the script to be checked. # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml shell:check: - desc: Check for problems with shell scripts + desc: | + Check for problems with shell scripts. + Environment variable parameters: + - SCRIPT_PATH: path of the script to be checked. cmds: - | if [[ "{{.SCRIPT_PATH}}" == "" ]]; then @@ -25,11 +26,12 @@ tasks: --format={{default "tty" .SHELLCHECK_FORMAT}} \ "{{.SCRIPT_PATH}}" - # Parameter variables: - # - SCRIPT_PATH: path of the script to be checked. # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml shell:check-mode: - desc: Check for non-executable shell scripts + desc: | + Check for non-executable shell scripts. + Environment variable parameters: + - SCRIPT_PATH: path of the script to be checked. cmds: - | if [[ "{{.SCRIPT_PATH}}" == "" ]]; then @@ -40,11 +42,12 @@ tasks: - | test -x "{{.SCRIPT_PATH}}" - # Parameter variables: - # - SCRIPT_PATH: path of the script to be formatted. # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml shell:format: - desc: Format shell script files + desc: | + Format shell script files. + Environment variable parameters: + - SCRIPT_PATH: path of the script to be formatted. cmds: - | if [[ "{{.SCRIPT_PATH}}" == "" ]]; then diff --git a/workflow-templates/assets/npm-task/Taskfile.yml b/workflow-templates/assets/npm-task/Taskfile.yml index 810ec9a6..23d46967 100644 --- a/workflow-templates/assets/npm-task/Taskfile.yml +++ b/workflow-templates/assets/npm-task/Taskfile.yml @@ -2,11 +2,12 @@ version: "3" tasks: - # Parameter variables: - # - PROJECT_PATH: path of the npm-managed project. Default value: "./" # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/npm-task/Taskfile.yml npm:install-deps: - desc: Install dependencies managed by npm + desc: | + Install dependencies managed by npm. + Environment variable parameters: + - PROJECT_PATH: Path of the npm-managed project (default: "./"). run: when_changed dir: | "{{default "./" .PROJECT_PATH}}" From db6a442f0dc1cca683eae5887437f724713a3453 Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 20 Jun 2025 19:31:20 -0700 Subject: [PATCH 2/3] Document task environment variable parameters Some tasks accept input via environment variables. It is important to document these parameter variables. Previously, the parameter environment variables of these tasks were undocumented. Typically, the documentation is done in the task description, to make the information easily accessible to contributors via the `task list` output. However, this approach was intentionally eschewed in the case of the `yaml:lint` task, where the documentation was instead placed in a comment. The reason is that this task's parameter variable is only useful when the task is executed by a GitHub Actions workflow, as is done already in the "Check YAML" workflow. So the contributor running the task from the command line has no need for this information and thus including it in the description would only clutter up the `task list` output with content useless to the reader of that output. --- Taskfile.yml | 2 ++ .../assets/check-go-task/Taskfile.yml | 17 ++++++++++++++--- .../assets/check-toc-task/Taskfile.yml | 6 +++++- .../assets/check-yaml-task/Taskfile.yml | 2 ++ 4 files changed, 23 insertions(+), 4 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index f61f5dbc..08e94edb 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -1052,6 +1052,8 @@ tasks: echo "{{.RAW_PATH}}" fi + # Environment variable parameters: + # - YAMLLINT_FORMAT: yamllint output format (default: colored). # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-yaml-task/Taskfile.yml yaml:lint: desc: Check for problems with YAML files diff --git a/workflow-templates/assets/check-go-task/Taskfile.yml b/workflow-templates/assets/check-go-task/Taskfile.yml index cd5488d6..f2181f1f 100644 --- a/workflow-templates/assets/check-go-task/Taskfile.yml +++ b/workflow-templates/assets/check-go-task/Taskfile.yml @@ -4,21 +4,32 @@ version: "3" tasks: # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml go:fix: - desc: Modernize usages of outdated APIs + desc: | + Modernize usages of outdated APIs. + Environment variable parameters: + - GO_MODULE_PATH: Path of the Go module root (default: {{.DEFAULT_GO_MODULE_PATH}}). + - GO_PACKAGES: List of Go packages to modernize (default: all packages of the module). dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}" cmds: - go fix {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml go:format: - desc: Format Go code + desc: | + Format Go code. + Environment variable parameters: + - GO_MODULE_PATH: Path of the Go module root (default: {{.DEFAULT_GO_MODULE_PATH}}). + - GO_PACKAGES: List of Go packages to modernize (default: all packages of the module). dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}" cmds: - go fmt {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml go:lint: - desc: Lint Go code + desc: | + Lint Go code + Environment variable parameters: + - GO_MODULE_PATH: Path of the Go module root (default: {{.DEFAULT_GO_MODULE_PATH}}). dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}" cmds: - | diff --git a/workflow-templates/assets/check-toc-task/Taskfile.yml b/workflow-templates/assets/check-toc-task/Taskfile.yml index 38c0e250..758b3fef 100644 --- a/workflow-templates/assets/check-toc-task/Taskfile.yml +++ b/workflow-templates/assets/check-toc-task/Taskfile.yml @@ -4,7 +4,11 @@ version: "3" tasks: # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-toc-task/Taskfile.yml markdown:toc: - desc: Update the table of contents + desc: | + Update the table of contents. + Environment variable parameters: + - MAX_DEPTH: maximum heading depth for inclusion in ToC. + - FILE_PATH: path to the file that contains the ToC. deps: - task: npm:install-deps cmds: diff --git a/workflow-templates/assets/check-yaml-task/Taskfile.yml b/workflow-templates/assets/check-yaml-task/Taskfile.yml index 19eb4aec..d0dcf5a2 100644 --- a/workflow-templates/assets/check-yaml-task/Taskfile.yml +++ b/workflow-templates/assets/check-yaml-task/Taskfile.yml @@ -2,6 +2,8 @@ version: "3" tasks: + # Environment variable parameters: + # - YAMLLINT_FORMAT: yamllint output format (default: colored). # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-yaml-task/Taskfile.yml yaml:lint: desc: Check for problems with YAML files From 34febc122406dc40147910c138c3e7aeb9f15e7b Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 20 Jun 2025 19:34:16 -0700 Subject: [PATCH 3/3] Standardize formatting of task parameter documentation Some tasks accept input via environment variables. These parameter variables are documented in the task description. A standard format has been established for that documentation. Previously, these descriptions did not follow the standardized format. Typically, the documentation is done in the task description, to make the information easily accessible to contributors via the `task list` output. However, a description was intentionally omitted for these tasks. The reason is these tasks are for internal use by other tasks, only serving to avoid code duplication. So the tasks should not be listed in the `task list` output. Task actually has a feature for marking such tasks as internal, but unfortunately that only works for the standard way of calling a task from another task, which can not be used in this case where the output of the task must be captured. For this reason, the task documentation is intentionally done via a comment instead of the description as would be done for a contributor facing task. --- Taskfile.yml | 8 ++++++-- workflow-templates/assets/windows-task/Taskfile.yml | 8 ++++++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 08e94edb..72141b95 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -1018,7 +1018,9 @@ tasks: fi - shfmt -w "{{.SCRIPT_PATH}}" - # Make a temporary file named according to the passed TEMPLATE variable and print the path passed to stdout + # Make a temporary file and print the path passed to stdout. + # Environment variable parameters: + # - TEMPLATE: template for the format of the filename. # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml utility:mktemp-file: vars: @@ -1039,7 +1041,9 @@ tasks: vars: RAW_PATH: "{{.RAW_PATH}}" - # Print a normalized version of the path passed via the RAW_PATH variable to stdout + # Print a normalized version of the path to stdout. + # Environment variable parameters: + # - RAW_PATH: the path to be normalized. # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml utility:normalize-path: cmds: diff --git a/workflow-templates/assets/windows-task/Taskfile.yml b/workflow-templates/assets/windows-task/Taskfile.yml index 59a4d393..8d507f90 100644 --- a/workflow-templates/assets/windows-task/Taskfile.yml +++ b/workflow-templates/assets/windows-task/Taskfile.yml @@ -2,7 +2,9 @@ version: "3" tasks: - # Make a temporary file named according to the passed TEMPLATE variable and print the path passed to stdout + # Make a temporary file and print the path passed to stdout. + # Environment variable parameters: + # - TEMPLATE: template for the format of the filename. # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml utility:mktemp-file: vars: @@ -13,7 +15,9 @@ tasks: vars: RAW_PATH: "{{.RAW_PATH}}" - # Print a normalized version of the path passed via the RAW_PATH variable to stdout + # Print a normalized version of the path to stdout. + # Environment variable parameters: + # - RAW_PATH: the path to be normalized. # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml utility:normalize-path: cmds: