[pull] main from arduino:main #41
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
![pull[bot]](https://avatars.githubusercontent.com/in/12910?s=60&v=4){kind=small}
The "codespell" tool is used to check for commonly misspelled words in the project files. This check should be performed on all files that are maintained by humans within the project. For the sake of efficiency, it should not be performed on externally maintained or machine generated files, since there is nothing that can be done within the project to resolve any misspelled words detected there. So the "asset" codespell configuration file contains a list of common externally maintained or machine generated paths to exclude. Previously the exclusions assumed the files would only be present in the root of the repository. Although that is most common, in some cases they may also be present in subfolders under the repository. The list of exclusions is hereby adjusted to cover those paths as well.
…ation The path of the dependencies manifest files must be defined in the Dependabot configuration for each "package ecosystem" entry. When implementing support for managing GitHub Actions workflows dependencies, the Dependabot developers made the inexplicable decision that, unlike any other ecosystem, Dependabot would look for the workflows under the `.github/workflows` subfolder of the specified path, rather than the actual path that is provided. Support for actually using the path specified by the configuration was later added. Since the configuration required by the original behavior was quite unintuitive, it is hereby changed to the actual path of the workflows in the repository.
Dependabot is used to keep the project dependencies updated. Dependabot periodically checks for available updates, and if found submits a pull request. The frequency of the update checks is configurable. Despite the name, the "daily" schedule configuration previously used actually only runs on weekdays. Maintenance of open source software projects is not necessarily limited to weekdays (and in the case of volunteer projects, is more likely to occur on weekends). So the weekday-ly update checks tended to result in a concentration of Dependabot pull requests on Mondays. This unnecessarily added to the busyness of an already busy day.
Configure codespell to ignore generated files in subfolders
Use explicit path for GitHub Actions workflows in Dependabot configuration
Configure Dependabot to check for updates daily
Shell scripts in Arduino tooling projects are formatted according to the style implemented by the shfmt formatting tool. In addition to standalone script files, significant quantities of complex shell code is also found in the asset tasks and workflows. shfmt can not be used to format this code (both due to the fact it is in the form of strings in YAML documents, and due to the fact that it is actually templates of shell code (making use of the templating features of Task and GitHub Actions) rather than complete shell code). However, it still makes sense to align the formatting of this code with the standardized shell code style where doing so is feasible.
Standardize formatting of shell code in tasks and workflows
The project's GitHub Actions workflows and tasks contain complex shell command lines. With the use of the line continuation operator, these commands can be split into multiple code lines. This improves readability by providing a visualization of the command structure. It also improves maintainability by making diffs for changes to these commands more clear. The readability can be further improved by indentation of the subsequent lines of the command in a manner that visually conveys the structure. Previously, in cases where multiple commands are chained via control or list operators, the subsequent commands were indented relative to the prior command in the chain. Although this did help to visually convey the structure, it also resulted in excessive levels of indentation. It also resulted in some visual ambiguity between indentation used for arguments to a command, and that for subsequent commands in the chain. For these reasons, the determination was made to not indent the subsequent commands in the chain. The structure is communicated by placing the operator linking the commands on a dedicated line.
Avoid excessive indentation in shell commands
The project's GitHub Actions workflows and tasks contain complex shell command lines. With the use of the line continuation operator, these commands can be split into multiple code lines. This improves readability by providing a visualization of the command structure and avoiding excessive line lengths. It also improves maintainability by making diffs for changes to these commands more clear. Previously this was done in many commands, but not consistently throughout the project.
Split shell commands into multiple lines for readability
The `run` keys of the steps in the GitHub Actions workflows contain complex shell command lines. The readability of this code is improved by selectively adding blank lines to separate it visually into logical groupings.
Add blank lines to visually group shell command lines
The project Python package dependencies are managed by the "Poetry" tool. Previously, the version of Poetry was not managed in any way. The GitHub Actions workflows used whichever version of Poetry happened to be installed on the runner machine. This meant that the GitHub Actions workflows could break at any time through the Poetry installation on the runner machine being updated to an incompatible version. The contributors used whichever version of Poetry happened to be installed on their machine. This meant that they might get different results from that produced by the environment of the GitHub Actions workflows. The better solution is to take the same approach for managing the Poetry dependency as is done for the project's other dependencies: * Install a specific version of Poetry according to a single source of versioning data. * Use the Dependabot service to get automated update pull requests. The logical place to define the Poetry package dependency version is in pyproject.toml, as is done for all other Python package dependencies. Dependabot has support for two different forms of dependency data in the pyproject.toml file: * Original Poetry data format, under the `tool.poetry` table * PEP 621 format data, under the `project` table Since Poetry can't be used to manage itself (it is instead installed using the "pipx" tool), the obvious approach would be to define the Poetry dependency via the `project` table in the file. However, this is not possible because if a `tool.poetry` table is present in pyproject.toml, Dependabot ignores the dependencies data from the `project` table. So it is necessary to place the data for the Poetry dependency under the `tool.poetry` table of the file. A special dependencies group is created for this purpose. That group is configured as "optional" so that it won't be installed redundantly by `poetry install` commands. Unfortunately pipx doesn't support using pyproject.toml as a dependency configuration file so it is necessary to get the Poetry version constraint for use in the dependency argument of the `pipx install` command by parsing the project.toml file.
The templates and documentation contain reference links to provide additional information to the users and maintainers. The targets of some of these links have moved since the time they were added. Although the user could still reach the intended content via a redirect, it is best not to rely on redirects continuing to work indefinitely. So the URLs are hereby updated to point directly to the target content.
Projects may use data files written in the TOML language. A common example of such is the `pyproject.toml` file present in projects that use the Poetry Python package management tool (either for project code dependencies, or development tools). In cases where the TOML content is edited directly by human contributors, it will be useful to provide code formatting infrastructure for TOML files, and to enforce consistent formatting. This is easily accomplished by adding TOML support to the existing code formatting infrastructure via the "prettier-plugin-toml" plugin for the Prettier formatting tool. Poetry's `poetry.lock` file is also written in the TOML language. This file is automatically generated and never manually edited. In this case, the automatically generated content is accepted as-is. So Prettier is configured to exclude the `poetry.lock` file from formatting.
Paths in some workflows and tasks are configured via variables. Previously, when a value specified a folder path, a
trailing slash was added. The intent behind this was to make it slightly more clear that the value was referring to a
folder (e.g., `./` vs. `.`). However, this practice can be harmful in the case where the value is used as a base
component in a path, as then it is most appropriate to omit the path separator in the concatenation code, which is at
all clear (e.g., `FOO_PATH: foo/`, `{{.FOO_PATH}}bar` -> `foo/bar`). And if the separator is used in the concatenation
code, it results in a confusing double separator in the resulting path (e.g., `FOO_PATH: foo/`, `{{.FOO_PATH}}/bar` ->
`foo//bar`). The benefit of the trailing slash on the variable definition is miniscule at most, since the variable name,
documentation, and other context should make it obvious that the value is a folder path. So the harm of this approach
outweighs the benefit.
For this reason, it is better to omit the trailing slash in the variable definition (e.g., `FOO_PATH: foo`,
`{{.FOO_PATH}}/bar` -> `foo/bar`). Even though this approach is not relevant in cases where the path is not used as a
base component, it is best to be consistent in this practice.
…ters For the sake of efficiency, GitHub Workflows should be configured to only be triggered when relevant files are modified. This filtering is done via the `paths` mapping. "Globstar" patterns are supported in paths filters. This will cause the filter to match the matching files in any path under the repository. Previously, this was done for the `.npmrc` npm configuration file in various workflows. Although this is appropriate in the "Check npm" workflow, which supports checking npm-based projects in subfolders of the repository, it is not appropriate for the other workflows which do not have such support (and likely don't need it). In order to improve the efficiency of the workflows, the globstars are removed from the `.npmrc` path filters in the workflows where it is not appropriate.
…ions These workflows support multiple projects in subfolders of the repository. The version of the frameworks (Go and Node.js) to use is determined from the content of the metadata files. Previously the workflow always used the file located in the root of the repository. The versioning data in that file won't necessarily be correct for the projects in subfolders, so the metadata for the individual project should be used instead.
A repository might contain multiple npm-managed projects. For this reason, the appropriate npm-managed tasks have a parameter environment variable that allows it to be configured for an arbitrary path, with the "Check npm" workflow having a job matrix of paths to pass. Generally, even if there are multiple npm-managed projects, there will be one primary project that is most often the target of contributor operation. Since it would be inconvenient for the contributor to pass the environment variable path every time they want to run a task for that primary project, the tasks are configured to have a default path which is used if the variable is not defined by the user. Since the primary npm-managed project would typically be in the root of the repository, the default value is set to the root. In the case where the primary npm-managed project is not in the root of the repository, the template installer will need to adjust this. Previously the default was hard coded in each individual task. The template will be made easier to install by defining the default in a single place via a friendly taskfile variable, following the convention already established by the templates for Go-based projects.
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.
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.
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.
Update redirecting URLs in reference links
Manage versioning of Poetry tool dependency
Use relevant metadata file when determining framework dependency versions
Make default npm project path configurable via taskfile variable
Improve task parameter environment variable documentation
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
See Commits and Changes for more details.
Created by
pull[bot] (v2.0.0-alpha.3)
Can you help keep this open source service alive? 💖 Please sponsor : )