In the event the checks on a submission PR fails, the bot comments with instructions for how the checks can be triggered
to run again once the user has resolved the issue. One option is to comment on the PR thread, mentioning ArduinoBot.
GitHub automatically linkifies mentions to the user's profile page, which occurs in these instructions. The ArduinoBot
profile page is not of relevance or interest in this context, so there is no benefit to providing a one click path for
its access. In addition, the link makes the text more difficult to copy. So it's better to prevent its linkification,
which is achieved by wrapping the text in backticks.
In the event the cause of a submission check failure is resolved externally, the user can trigger the "Manage PRs"
workflow run by mentioning ArduinoBot in a reply to the PR thread. Unlike a workflow run triggered by a push to the pull
request, GitHub Actions does not provide any visible indication on the PR page of the workflow run in progress. Instead,
we have configured the workflow so that the bot immediately comments on the PR thread so that the user is not left
wondering whether their comment had any effect as the longer process of the submission checks finishes before the
feedback about their result can be provided.
With the idea that some users might like to get a progress indicator in the time between the initial comment and the
final feedback from the workflow run, I added a link to the workflow runs page. However, we received feedback from
testers that encountering the fairly cryptic workflow run logs causes confusion. So we are trying to avoid leading users
toward those logs. Since the link does just that and is not necessary, it's best to simply remove it.
The "Manage PRs" GitHub Actions workflow processes pull requests submitted to the repository. It is intended to allow
completely automated submissions of libraries. The feedback mechanism used by the system is comments on the pull request
thread. These comments should provide all the necessary feedback about the process, including whatever is needed to
bring a submission into compliance in the event the automated checks find it to not meet the requirements.
From feedback provided by testers, we learned that they navigated to the workflow run logs provided by GitHub Actions
while trying to learn what the problem was with their submission.
The workflow run logs provide output from the internal workings of the system that is only of interest for developers
troubleshooting a malfunction of the system itself. We never intended to use them as a channel for communicating to the
regular users of the system. Users of the system may find them quite cryptic. Since this is an interface generated by
GitHub Actions, without much capability for customization, it would be quite difficult for us to improve their
readability for the normal user. Those efforts would also require an increase in the complexity of the workflow and make
it more difficult to maintain.
I think there are two possible paths a normal user would be likely to follow to the workflow logs while trying to
understand why their submission was not accepted:
- The check status UI shown at the bottom of the PR comment thread ("Some checks were not successful")
- Workflow run failure email notification ("Manage PRs: Some jobs were not successful: View workflow run")
These pathways are either less enticing or absent when a workflow run is successful.
Previously, there were two possible causes for a run of the "Manage PRs" workflow to fail:
- Submitted library did not meet the Library Manager requirements
- An unexpected error from one of the workflow steps
Since we already are using comments from the bot to communicate about the former, the workflow run failure status
indicators provided by GitHub Actions are superfluous. The latter only occurs under extraordinary and circumstances so
its effect on the user experience is not of concern.
So the way to improve the user experience is to configure the workflow to only fail on unexpected errors, only commenting
and blocking merge in the event of expected errors.
Hello!
I own the UbxGps library and it's been in the registry for a while, but with my previous GitHub username (1oginov).
I changed it to loginov-rocks and just aligning a link to the repository.
Link in the library.properties has already been updated: https://github.com/loginov-rocks/UbxGps/blob/main/library.properties#L8
Thank you!
* Update repositories.txt
* add github.com/newdigate/teensy-sample-flashloader
added a new library - a tiny utility to load audio samples to external flash memory from the uSD card on a teensy 4.1
* add TeensyAudioSampler - github.com/newdigate/teensy-polyphony
* Update repositories.txt
* add github.com/newdigate/teensy-sample-flashloader
added a new library - a tiny utility to load audio samples to external flash memory from the uSD card on a teensy 4.1
Since we already have the Dependabot infrastructure in place for managing dependencies of the project's Go code and
GitHub Actions workflows, it makes sense to do the same for the newly introduced Go and Python dependencies as well.
This configuration is applied to the `production` branch (using the `target-branch` key), but it must be added to the
configuration file in the default branch (`main`) because Dependabot only pays attention to the default branch's
configuration file.
Reference:
https://docs.github.com/en/code-security/supply-chain-security/configuration-options-for-dependency-updates#about-the-dependabotyml-file
In the event of a problem with a submission, the comments on the pull request thread. Due to the use of a matrix job to
support submissions of any number of libraries in a single PR, this might consist of multiple comments. Adding a standard
prominent prefix (❌ **ERROR:**) to all error messages will ensure that the most important part of this information is
not missed.
Dependabot will periodically check the versions of all actions used in the GitHub Actions workflows of the `production`
branch. If any are found to be outdated, it will submit a pull request to update them.
NOTE: Dependabot's PRs will occasionally propose to pin to the patch version of the action (e.g., updating
`uses: foo/bar@v1` to `uses: foo/bar@v2.3.4`). When the action author has provided a major version ref, use that instead
(e.g., `uses: foo/bar@v2`). Dependabot will automatically close its PR once the workflow has been updated.
More information:
https://docs.github.com/en/github/administering-a-repository/keeping-your-actions-up-to-date-with-dependabot
The period to close the sentence might be interpreted as part of the example repository URL. Since it doesn't provide any
benefits for the readability of this sentence and might cause confusion, it's best to remove it.
It turns out there are a couple of extra steps in the workflow for submitting a PR via the GitHub web interface for those
who don't have write access in the repository. I missed these while developing the instructions due to having write
access.
The process is intended to be as simple, fast, and flexible as possible for the submitter. For this reason, there is
absolutely no expectation regarding where in `repositories.txt` the library repository URL should be added. The system
will work fine no matter if it's at the start, end, alphabetical order, or some random spot. If we do want to restore
alphabetical order periodically, a maintainer can easily do that.
For this reason, there was previously no mention of the proper location in the list for submitters to use, since there is
none. However, this ambiguity might actually make the process less friendly to those who are left wondering. So it's best
to explicitly state that the location doesn't matter.
This link was intended to provide readily accessible information on what the term "fork" means in this context. However,
it comes directly after mention a link, which is referencing the URL provided later in the sentence. This might result in
confusion about which of the two links is meant. Most library submitters will already know the meaning of the term "fork"
and those who don't will be able to find information about it easily enough, including by visiting the information about
pull requests linked to earlier in the document. So I think that it's better to remove this link.
This change to the "Manage PRs" workflow will cause the "github-actions" bot to add an approval pull request review to
submission PRs after they have passed all compliance checks, but before merging.
This is necessary to allow us to instate the "Require pull request reviews before merging" branch protection rule on
`main`, which will protect the repository from accidental pushes by the maintainers and administrators with write
permissions in the repository.
As an added benefit, this will more clearly indicate the status of a submission in the case where it is fully compliant
with the Library Manager requirements but an automated merge is not possible due to a merge conflict. In this case, the
bot will add an approval each time the workflow is triggered, but that is a reasonable behavior, and one permitted by the
PR review system (i.e., subsequent approvals will not cause a spurious workflow run failure, with either workflow trigger
event type).
The library submission instructions contained a step for selecting a radio button before committing. This radio button
only exists when editing a file in a repository you have write access to, which is why I encountered it while developing
the instructions.
Library submitters will not have these radio buttons and so instructions for using a non-existent UI element would
cause confusion.
We are no longer supporting the alteration of library releases. A release should be an immutable snapshot of the library.
Having multiple revisions of a library with the same identifier can cause confusion for the users and no need for a
library maintainer to do it since they can more easily make a new release, removing the old one from the repository if
absolutely necessary.
We will always provide support for removing problematic releases from the Library Manager index, and the FAQ provides
instructions for that procedure.
