The actions/setup-node GitHub Actions action is used to set up Node.js in the GitHub Actions runner machine.
The action supports obtaining the Node.js version to set up from the `engines.node` field of the package.json file.
This allows us to define the standardized version of Node.js for use by project contributors in a single place rather
than having to maintain multiple instances of that data.
Some of the assets use tools sourced from the npm software registry.
Previously, the version of the tools used was not controlled. This was problematic because:
- A different version of the tool may be used on the contributor's machine than on the CI runner, resulting in confusing
failures.
- The project is immediately subject to disruption or breakage resulting from a release of the tool.
---
These tools were installed via either of the following methods:
`npx <pkg>`
This approach has the following behaviors of interest:
https://docs.npmjs.com/cli/v8/commands/npx#description
> If any requested packages are not present in the local project dependencies, then they are installed to a folder in the npm cache, which is added to the PATH environment variable in the executed process.
> Package names provided without a specifier will be matched with whatever version exists in the local project. Package names with a specifier will only be considered a match if they have the exact same name and version as the local dependency.
This means that the version used was:
1. Whatever happens to be present in the local cache
2. The latest available version if it is not already present
`npm install --global <pkg>`
The latest available version of the package is used.
---
The new approach is to specify the version of the tools via the standard npm metadata files (package.json +
package-lock.json). This approach was chosen over the `npx <pkg>@<version>` alternative for the following reasons:
- Enables automated updates via Dependabot PRs
- Enables automated vulnerability alerts
- Separates dependency management from the asset contents (i.e., no need to mess with the taskfile or workflow on every
update)
- Matches how we are already managing Python dependencies (pyproject.toml + poetry.lock)
This project uses Node.js 16. Previously, although the workflows that were more closely related to the code were
configured to use this version, other workflows which also use Node.js/npm were using whichever version happened to be
pre-installed on the GitHub Actions runner.
Since the contributor will be using Node.js 16 on their local machine for all development and maintenance operations,
use of a different version by the GitHub Actions runner might result in confusing differences in results between the
local machine and the CI system.
This is avoided by setting the Node.js version in all applicable workflows. Following the existing convention, this is
done via an environment variable at the top of the workflow in order to facilitate the process of updating to a new
standard version of Node.js in the project.
This will make it easier for the maintainers to sync fixes and improvements in either direction between the upstream
"template" assets and their installation in this repository.
The paths filter is used to make GitHub Actions workflows more efficient and contributor friendly by preventing pointless
workflow runs from happening when only irrelevant files were modified. However, careful consideration must be given to
which files are relevant. In some cases, this can lead to a very lengthy list of path patterns. These can be compressed
down through the use of advanced patterns.
There are two file extensions in common use for YAML files: `.yaml` and `.yml`. Although this project uses `.yml`
exclusively for YAML files, these are standardized workflows which might be applied to projects that have established the
use of the other extension. It will be most flexible if it supports both.
This useful action is an integral part of the CI system. Now that it has a dedicated repository and a new name, the CI
workflows must be updated to use the latest release version of the action.
Change project name to "arduino/setup-task"
The Task documentation consistently refers to the tool as "Task". Taskfile is the term used for Task's configuration file.
This action is setting up the Task tool, not setting up the Task configuration file, so "arduino/setup-task" is more
appropriate than "arduino/setup-taskfile".
On every push and pull request that affects relevant files, and periodically, check the repository's Markdown files for
problems:
- Use markdownlint to check for common problems and formatting.
- Use markdown-link-check to check for broken links.
Arduino's Markdown style is defined by the `.markdownlint.yml` file.
In the event the repository contains externally maintained Markdown files, markdownlint can be configured to ignore them
via a `.markdownlintignore` file:
https://github.com/igorshubovych/markdownlint-cli#ignoring-files
markdown-link-check is configured via the `.markdown-link-check.json` file:
https://github.com/tcort/markdown-link-check#config-file-format
