When there is a problem with the submission that must be resolved in the library repository, a comment mentioning
`@ArduinoBot` is used to trigger the "Manage PRs" workflow.
We are accustomed to seeing the checks status in the PR thread when workflows are running. However, with a comment
triggered workflow this does not happen. The only indication of the workflow running is on the "Actions" tab. This can
leave the submitter wondering if their comment had any effect as the workflow takes some time to run before providing
feedback.
This uncertainty can be avoided by making the bot immediately comment to acknowledge that the check is in progress.
Previously, as soon as a submission was compliant, the PR was merged silently. This might leave the submitter wondering
whether the submission process is complete.
There is some uncertain delay for the library release to be added to the server, the index to be generated, and the index
to propagate through the CDN, which might result in an increased support burden as the submitters comment or open issues
asking what is happening.
This is avoided by making the bot comment on the PR thread after the PR is merged, notifying the submitter that the
process was successful and that there will be some delay before the library is available from Library Manager.
Indexer logs URLs are provided for each submission, allowing the submitter to monitor the indexing process, both
immediately after the acceptance, as well as after they make future releases.
The "Manage PRs" GitHub Actions workflow generates a matrix job for each library submitted by the PR. The default job
name is generated from the job's matrix object. This contains the complete submission data, which results in a long and
somewhat cryptic job name that can make the workflow run more difficult to interpret.
The only necessary information is the description of the job's purpose ("check") and the submission URL (multiple URLs
per PR are supported). A custom job name allows for only using this information in the job name.
The yamllint configuration advocates for keeping line lengths within 120 characters. While exceeding this length only
results in a warning, I think it is beneficial to stay within that limit when it is possible and doesn't have a harmful
effect. In that spirit, I have reduced the long lines where this was easily done. There remain a few that are either not
possible or else not reasonable to reduce, and that's OK.
After I set up caching in the template workflows, doubts were raised about whether it provided any benefits. I don't know
enough about this subject to make a call on that and I have been unable to get any more information on the subject.
Since the caching significantly increases the complexity of the workflows, which may make them more difficult to maintain
and contribute to, I think it's best to just remove all the caching for now. I hope to eventually be able to revisit this
topic and restore caching in any workflows where it is definitely beneficial.
On every push and pull request that affects relevant files, and periodically, run yamllint to check the YAML files of
the repository for issues.
The .yamllint.yml file is used to configure yamllint:
https://yamllint.readthedocs.io/en/stable/configuration.html
It will be helpful to the reader to be able to get an overview of the documentation content and quickly navigate to the
section of interest.
The table of contents are automatically generated using the markdown-toc tool.
Because it can be easy to forget to update the table of contents when the documentation content is changed, I have added
a CI workflow to check for missed updates to readme ToC. On every push or pull request that affects the repository's
documentation, it will check whether the table of contents matches the content.
Now that the parser tool is moved out of the repository, it makes less sense to use the taskfile-based approach for the
CI infrastructure. In order to make the repository more contributor-friendly, the license checking system is now
confined to a single workflow file.
Now that the parser tool is moved out of the repository, it makes less sense to use the taskfile-based approach for the
CI infrastructure. In order to make the repository more contributor-friendly, the documentation and configuration
checking system is now confined to the .github subfolder.
Now that the parser tool is moved out of the repository, it makes less sense to use the taskfile-based approach for the
CI infrastructure. In order to make the repository more contributor-friendly, the spell checking system is now reduced to
a single workflow file.
This approach allows the diff to be written directly to a file, rather than needing to sanitize the contents of the
output from the octokit/request-action before writing it to the file via the shell.
The index source file contains the normalized URL and the metadata that can't be derived from the library releases
("types" data and locked name) for each of the libraries in the Library Manager index. It's most appropriate to store it
in the same repository as the submission list.
I had intended to test these out but didn't get around to it. The workflow_dispatch might be convenient, but it's not at
all essential since the same thing can be accomplished by commenting on the PR.
Rather that committing directly to the index source file repository, save the index entry to a workflow artifact, which
will be consumed by the system that updates the index source file.
Submissions of libraries to the Arduino Library Manager index can be done by submitting a pull request adding repositor
URLs to the list. The submissions are checked for compliance wih the requirements for addition to the index and as soon
as they are passing the pull request is merged and the entries are pushed to the index source file.
