Background
----------
The Arduino Library Manager Registry repository receives thousands of pull requests from a large number of community
contributors. The great majority of these contributors behave in a responsible manner. Unfortunately this repository is
regularly the subject of irresponsible behavior. The small number of people who behave irresponsibly consume a
significant amount of the finite maintenance resources available for maintenance of Arduino's repositories.
Communication is always the first measure taken in these cases. This is done automatically by the "Manage PRs" workflow,
and then by the registry maintainer when it becomes clear that the user has disregarded the comments from the bot.
Unfortunately it is regularly the case that the user simply disregards all communication and continues their pattern of
irresponsible behavior unchecked.
Alternatives
------------
GitHub provides tools for dealing with harmful behavior:
- Report user
- Block user
Reporting a user is the appropriate measure in cases of malicious behavior, and the account is usually banned from the
site relatively quickly after a legitimate report is made. However, the irresponsible behavior in the registry
repository is not overtly malicious and so reporting the user in these cases would not be appropriate or effective.
At first glance, the block feature seems ideal. However, it can only be done at an organization-wide level, and by an
organization administrator. The repository maintainer is not an organization administrator, so this makes the feature
inconvenient to use. There is no sign of these users interacting with other repositories in the `arduino` organization,
and so there is no benefit to blocking them at organization scope. In addition, in order to make it more difficult to
circumvent the access restriction, we need the ability to block requests for libraries owned by an entity who has
established a pattern of irresponsible behavior, regardless of which user submits the request.
So the tools provided by GitHub are not suitable and a bespoke system must be implemented.
Access Levels
-------------
Allow: the user may submit requests for any library, even if registry privileges have been revoked for the owner of the
library's repository. This access level will only be granted to registry maintainers, in order to allow them to make
exceptions for specific libraries owned by an entity whose privileges have been revoked.
Default: the user may submit requests for any library, unless registry privileges have been revoked for the owner of the
library's repository.
Deny: the user may not submit requests. Requests from users with "default" access level for any library repository owned
by the entity (user or organization) are denied.
In cases where a request is declined due to revocation of Library Manager Registry privileges, the "Manage PRs" workflow
will automatically make an explanatory comment, including a link that provides more details about the cause of the
revocation. It will also close the PR in the case where it is not possible for the requester to resolve the problem:
* The requester's Library Manager Registry privileges have been revoked
**-OR-**
* The owners of all library repositories which are the subject of the request have lost Library Manager Registry
privileges.
The goal is to make it possible for any community member to submit libraries to the registry, regardless of their level
of relevant technical expertise. For this reason, the project documentation includes a detailed and comprehensive set of
instructions for submitting a library.
Since the time these instructions were written, a regression was introduced into the GitHub website:
When creating a commit via the GitHub web interface, the dialog allows the user to select which branch the commit should
be made to. Typically this includes two options:
- "Commit directly to the <target branch> branch"
(where "<target branch>" is the branch the user had selected when they initiated the procedure)
- "Create a new branch for this commit and start a pull request"
If the branch protection rules configured for the target prevent the user from committing to that branch, then the first
of the options is removed (which is the appropriate behavior).
Following GitHub's regression, under the conditions produced by the previous submission procedure, the determination of
whether the first option should be disabled is based on the branch protection configuration of the
arduino/arduino-registry repository, not of the library submitter's fork. This is incorrect because the fork does not
inherit the branch protection settings of the parent, meaning the target branch will never be protected in the fork and
thus that the commit to that branch should be allowed in the dialog.
Because we do have branch protection rules enabled for the `main` branch of the `arduino/library-registry` repo, this
bug causes the default setting in the dialog to be changed from "Commit directly to the main branch" to
"Create a new branch for this commit and start a pull request" when the documented submission procedure is performed.
Strangely, the user flow is significantly different depending on which of these options is selected. The user flow when
"Create a new branch for this commit and start a pull request" is selected forces the user to submit the PR to their own
fork repository instead of to arduino/library-registry. It is essential for the PR to be submitted to
arduino/library-registry so this change in the outcome of the previous documented submission procedure as a side effect
of GitHub's regression is catastrophic.
The submission instructions are hereby updated to once again produce a correct submission. Unfortunately, the procedure
that is now required is more complex and less intuitive than the previous one. In order to mitigate this, I made an
effort to be extra explicit both in describing the actions to be performed, as well as describing the expected result of
each action.
I reported the regression to GitHub. I will change the documentation back to using the more friendly submission
procedure once it is fixed.
High quality feedback via GitHub issues is a very valuable contribution to the project. It is important to make the
issue creation and management process as efficient as possible for the contributors, maintainers, and developers.
Issue templates are helpful to the maintainers and developers because it establishes a standardized framework for the
issues and encourages the contributors to provide the essential information.
The contributor is now presented with a web form when creating an issue. In the case of the library registration
maintenance requests, these are for the specific information the registry maintainers require. For more general bug
reports or feature requests, they use multi-line input fields that have the same formatting, preview, and attachment
capabilities as the standard GitHub Issue composer, in addition to other form components such as menus and checkboxes
where appropriate.
The use of this form-based system should provide a better experience for the contributors and library maintiners while
also resulting in higher quality issues by establishing a standardized framework for the issues and encouraging
contributors to provide the essential information.
A template chooser allows the contributor to select the appropriate template type, redirects support requests to the
appropriate communication channels via "Contact Links", and provides a prominent link to security policy to guide any
vulnerability disclosures.
The clear separation of the types of issues encourages the reporter to fit their report into a specific issue category,
resulting in more clarity. Automatic labeling according to template choice allows the reporter to do the initial
classification.
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.
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.
UI element label text mentions intermingled with prose text in documentation can harm readability, especially when
skimming. For this reason, I think it is helpful to add formatting to clearly distinguish this text visually.
The previous wording was verbose and unclear, the result of copy/paste-based writing.
A backwards compatibility anchor tag is not needed in this case because this documentation has not yet been published,
meaning that there has been no opportunity for the creation of external links pointing to the old ID.
The official policy is that anyone is allowed to submit any library to Library Manager, regardless of whether they have
any involvement with the development and maintenance of the library.
As someone very much involved in the submission process, I have always wondered this myself. So it is very important to
clearly document this.
Some of the wording of the existing documentation implied that only the owner of the library could submit it, so this
text has been adjusted as well.
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.
It is essential to clearly communicate the Library Manager requirements to the submitters. Previously, these requirements
were scattered throughout the FAQ. Consolidating them into unified lists, then referencing that information from the
other parts of the documentation makes it easier for the user to learn what are the requirements and easier for the
documentation to be maintained.
An FAQ hosted in the `arduino/Arduino` repository's wiki:
https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ
has long served as the canonical guide for the traditional process for submitting libraries to the Library Manager index.
Now that the submission process and support for the process has been moved from `arduino/Arduino` to this dedicated
repository, it makes sense to also host the FAQ content here.
This commit imports the exact unmodified content of the FAQ from
819425389e
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.
