From e4b9373eb16c40f1901f775eed2f34f0fb36c7f1 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 7 Sep 2025 20:08:34 -0700 Subject: [PATCH 1/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 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Taskfile.yml b/Taskfile.yml index c883e084..e543a25c 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -342,7 +342,11 @@ tasks: # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/test-go-task/Taskfile.yml go:test: - desc: Run unit tests + desc: | + Run unit tests. + Environment variable parameters: + - GO_MODULE_PATH: Path of the Go module root (default: {{.DEFAULT_GO_MODULE_PATH}}). + - GO_PACKAGES: List of Go packages to test (default: all packages of the module). dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}" cmds: - | From c3b5a333e908ab3cfff3ebdc118b921082a09ab1 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 7 Sep 2025 20:10:07 -0700 Subject: [PATCH 2/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 | 64 ++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 44 insertions(+), 20 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index e543a25c..aeb8e8f1 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -289,14 +289,22 @@ 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}} @@ -313,7 +321,11 @@ tasks: # 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}}). + - GO_PACKAGES: List of Go packages to modernize (default: all packages of the module). dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}" cmds: - | @@ -378,7 +390,10 @@ tasks: # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml go:tidy: - desc: Refresh dependency metadata + desc: | + Refresh dependency metadata. + 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}}" vars: GO_VERSION: 1.24.0 @@ -387,7 +402,11 @@ tasks: # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml go:vet: - desc: Check for errors in Go code + desc: | + Check for errors in 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 test (default: all packages of the module). dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}" cmds: - go vet {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} @@ -458,21 +477,23 @@ tasks: markdownlint-cli \ "**/*.md" - # 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: {{.DEFAULT_NPM_PROJECT_PATH}}). dir: | "{{default .DEFAULT_NPM_PROJECT_PATH .PROJECT_PATH}}" cmds: - npm install - # 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: {{.DEFAULT_NPM_PROJECT_PATH}}). vars: # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/package.json SCHEMA_URL: https://json.schemastore.org/package.json @@ -636,11 +657,12 @@ tasks: flake8 \ --show-source - # 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 @@ -659,11 +681,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 @@ -674,11 +697,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 From a29f6f5cbf647dd36cde504ae53f10a3fea86707 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 7 Sep 2025 20:10:36 -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 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index aeb8e8f1..811c4f2f 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -717,7 +717,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: @@ -739,7 +741,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: