From d2e950d6178121a94c44f69e244d15f82da499d6 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 4 Jun 2025 00:17:32 -0700 Subject: [PATCH 1/2] 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 --- Taskfile.yml | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 49494a7..e474507 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -256,7 +256,7 @@ tasks: desc: | Install dependencies managed by npm. Environment variable parameters: - PROJECT_PATH: Path of the npm-managed project (default: {{.DEFAULT_NPM_PROJECT_PATH}}). + - PROJECT_PATH: Path of the npm-managed project (default: {{.DEFAULT_NPM_PROJECT_PATH}}). dir: | "{{default .DEFAULT_NPM_PROJECT_PATH .PROJECT_PATH}}" run: when_changed @@ -268,7 +268,7 @@ tasks: 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}}). + - PROJECT_PATH: Path of the npm-managed project (default: {{.DEFAULT_NPM_PROJECT_PATH}}). deps: - task: npm:install-deps vars: @@ -380,7 +380,7 @@ tasks: desc: | Install dependencies managed by Poetry. Environment variable parameters: - POETRY_GROUPS: Poetry dependency groups to install (default: install all dependencies). + - POETRY_GROUPS: Poetry dependency groups to install (default: install all dependencies). run: when_changed deps: - task: poetry:install @@ -407,7 +407,9 @@ tasks: poetry check \ --lock - # 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: @@ -418,7 +420,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: From a2d4d14a90ffadd529da973b175efa082ea3d2ab Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 4 Jun 2025 00:19:54 -0700 Subject: [PATCH 2/2] 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 | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index e474507..7af3e19 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -157,21 +157,33 @@ 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}}). + - GO_PACKAGES: List of Go packages to modernize (default: all packages of the module). dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}" cmds: - | @@ -186,7 +198,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 modernize (default: all packages of the module). dir: "{{default .DEFAULT_GO_MODULE_PATH .GO_MODULE_PATH}}" cmds: - go vet {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} @@ -435,6 +451,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