I originally set out to establish some logical order to the tasks on some indecipherable criteria. In the end, it
resulted in a jumble.
Alphabetical order is completely objective and it results in a fairly logical order in the end due to the the use of
prefixes on the task names according to their domain. The exception is that the convenience "umbrella" tasks have been
left at the top (in their own alphabetical order) so that they will have the maximum visibility as the most useful tasks.
Even that is not completely inconsistent, since these don't have a namespace prefix, and so might be imagined to have a
null global namespace prefix that would be sorted first.
The `fix` task provides a standardized interface for the developer to run all available automated correction processes.
Even though some such processes will likely be irrelevant at any given time, it can be more convenient, and often more
efficient, for a casual contributor to just run the "umbrella" task rather than inspecting the available tasks and
running each of the relevant ones individually.
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.
`npx --call` uses the native shell. The use of Bash code in the link check command passed to npx made it incompatible with Windows, even when the task was run from Bash.
After quite some struggles, I decided that it's simply too difficult to use npx for this application on Windows. The
workaround is to abandon the use of npx for this task on Windows and instead require Windows users to have
markdown-link-check installed and in PATH, providing a helpful error message in the event it is not.
Generated documentation content may contain links, and it is just as important to check these. This project does not
contain any generated documentation at the moment, so the generation task is left empty, but this is a sync with the
"template" task which is intended to be applicable to any project.
The markdownlint tool used to check for problems or style inconsistencies in the repository's Markdown content provides
an automatic correction capability for certain rules.
A dedicated task has been added for installing the project's Python dependencies via Poetry, and this should be used
throughout the taskfile in place of redundant direct commands.
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
On every push, pull request, and periodically, use the codespell-project/actions-codespell action to check for commonly
misspelled words.
In the event of a false positive, the problematic word should be added, in all lowercase, to the ignore-words-list field
of ./.codespellrc. Regardless of the case of the word in the false positive, it must be in all lowercase in the ignore
list. The ignore list is comma-separated with no spaces.
