The `ignore-words-list` and `skip` settings of the codespell configuration file may required project-specific adjustments
to fix false positives or avoid positives from externally maintained files. The other settings are universal. It will be
convenient to have the settings the user might need to adjust at the place of highest visibility in the configuration
file.
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.
The caret version constraint strikes a nice balance of allowing for benefiting from improvements to the dependency, but
stopping at a potentially breaking change indicated by a major version bump. A manual review should be done at that time
before updating the constraint to the next major version series.
The previous approach only set a minimum version constraint, with no restriction on breaking releases.
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.
The use of the `error` workflow command will cause the important error message output to be surfaced prominently in the
workflow run summary and log. The workflow run logs can be somewhat labyrinthine to those who don't work with them
regularly, so finding the previous output to determine what caused the failure might have been challenging.
Even if it works as intended, it is not clear what the effect is of the escaped quote at the end of the environment
variables in the shell commands used to check the license detection results. Wrapping the variable names in braces
ensures they are as expected and also makes the working of the code clear.
Placement of this information at the top of the file, where it is easy to find and edit, facilitates updates to the
workflows as the tool versions used for project development are bumped periodically.
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 is a standardized "template" configuration file intended to be applicable to any project, so even if not necessarily
relevant to every project, common files that should never be checked are all collected on the list.
