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 FAQ contains an introduction to the Arduino Library Manager. This is supplemented with a list of links to references
about the Library Manager interface in each of the Arduino development tools.
The never ending churn of the Arduino IDE website structure resulted in the breakage of the link to the Arduino Cloud
reference. It is hereby updated to point to the replacement page.
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.
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.
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.
These anchor tags provide compatibility with links created before the heading text was changed (anchors are automatically
generated for headings). Placing them below the headings caused the page to be scrolled to below the headings when
visited via their links.
The Library Manager indexer logs are available for each library in the index. Example:
http://downloads.arduino.cc/libraries/logs/github.com/cmaglie/FlashStorage/
This can be a valuable tool for monitoring the indexing of releases, allowing the library authors to troubleshoot without
the need for assistance from a maintainer of this repository.
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.
At the time it was created, there was only one official Arduino development application: Arduino IDE. Since that time,
Arduino Web Editor and Arduino CLI have been created, both of which implement Library Manager in their own manners.
Previously, library submitters were not exposed to the internal workings of the Library Manager index generation system,
so they only needed to be concern with the public index file. Now the submitters will be interacting directly with the
Library Manager submission list. This might lead to some confusion between that list and the Library Manager index, so
it's important to be clear in the terminology used in the documentation.
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
