arduino/library-registry
1
0
Fork 0
mirror of https://github.com/arduino/library-registry.git synced 2025-04-19 03:42:17 +03:00
Code
library-registry/FAQ.md
per1234 9b5ff78597 Add Library Registry access control system 
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.
2025-01-13 16:35:27 -08:00

14 KiB
Raw Permalink Blame History

Arduino Library Manager FAQ

Table of Contents

General

What is the Arduino Library Manager?

Library Manager is a feature of the Arduino development software which makes it easy for users to find, install, and update both official and 3rd party libraries.

  • In the Arduino IDE: Sketch > Include Library > Manage Libraries...
  • In Arduino CLI: arduino-cli lib --help
  • In Arduino Web Editor: all Library Manager libraries are pre-installed.

When a library is added to the library list, every release of the library will automatically be made available for installation via Library Manager. Users can set their preferences to display an update notification when a new version of any installed library on the list is available and easily update to the new version with just a couple clicks.

More information:

How is the Library Manager index generated?

The Library Manager index contains the data for every release of every one of the thousands of libraries that have been added to the Library Manager list. This index is used by Library Manager to provide installation and updates of the libraries as well as to generate automated documentation pages for the Arduino Library Reference.

Every hour, the automated Library Manager indexer system:

  1. checks every repository in the Library Manager list for new tags, updating the logs accordingly
  2. checks whether those tags meet the requirements for addition to the index
  3. adds entries to the index for compliant tags
  4. pushes the updated index to Arduino's download server

Submission

How can I add a library to Library Manager?

Follow the instructions here.

What are the requirements for a library to be added to Library Manager?

  • The library must be something of potential value to the Arduino community.
  • The submitter must behave in a responsible manner in their interactions with the Library Manager Registry.
  • The library must be fully compliant with the Arduino Library Specification.
  • The library must have a library.properties file, in compliance with the Arduino Library 1.5 format.
  • The library.properties file must be located in the root of the repository.
  • The library must not have the same library.properties name value (regardless of case) as another library previously added to the Library Manager list.
  • For 3rd party libraries, the name field in library.properties must not start with Arduino.
  • The library repository must not contain any .exe files.
  • The library repository must not contain a .development file.
  • The library repository must not contain any symlinks.
  • The library repository must not contain any files detected as infected by our antivirus scan.
  • The library repository must have a Git tag (or release) and must have been compliant with all the above requirements at the time of that tag.
  • The library repository must be hosted on a major Git-hosting website like GitHub, BitBucket or GitLab (other hosting sites may be considered on request).

Arduino has created a command line tool to check libraries for compliance with all the Library Manager requirements:

https://github.com/arduino/arduino-lint

Arduino Lint is also available as a GitHub Actions action that can be used in the CI systems of Arduino library repositories to ensure continued compliance:

https://github.com/arduino/arduino-lint-action

Who is allowed to add a library to Library Manager?

Everyone is welcome to submit libraries for inclusion in Library Manager, regardless of whether you are involved in the library's development.

Note that libraries will need to be compliant with all requirements in order to be accepted. If not, you will need to work with the library maintainer to achieve compliance.

Updates

How can I publish a new release once my library is in the list?

  1. Make sure the library is compliant with all requirements.
  2. Update the version in the library's library.properties).
  3. Tag the library's repository once more and push the new tag (or create a release if the library's Git-hosting site offers a way to do it, for example with GitHub "releases").

Our indexer checks for new releases every hour and will eventually fetch and publish the new release.

What are the requirements for publishing new releases of libraries already in the Library Manager list?

  • The library must be compliant with all the same requirements that apply to submissions.
  • The name property in library.properties must not have changed from the value it had when the library was submitted. If you must change the library name, see this.
  • The version property in library.properties must not be the same as it was in a tag previously added to the Library Manager index.

Why aren't releases of my library being picked up by Library Manager?

The Library Manager indexer job will reject any releases which aren't compliant with all the requirements.

You can check the indexer logs for information about what happened.

Can I check on library releases being added to Library Manager?

There is a dedicated web page for each library that shows the logs from the Library Manager indexer. The URL of the logs page is based on the library's repository URL:

http://downloads.arduino.cc/libraries/logs/<host>/<repository slug>/

For example, the Servo library is hosted at https://github.com/arduino-libraries/Servo, so its logs are at:

http://downloads.arduino.cc/libraries/logs/github.com/arduino-libraries/Servo/

How can I remove a release of my library from Library Manager?

If you discover a problem with the library release, simply fix the problem and make a new release. Library Manager defaults to installing the latest version of the library and offers updates to those with an older version installed, so this is the fastest and most effective method for distributing a fix to the users.

In the event a library release is later discovered to contain something that absolutely can not be published, we do allow removing releases from Library Manager on request by the following procedure:

  1. Delete the tag of the problematic release from the library's repository.
  2. Open an issue here, specifying the name of the library and the version number of the release that should be removed.

How can I change a library's name?

For the sake of continuity, libraries in the Library Manager list are locked to the name they had at the time they were added to the list. Changing the library name can be disruptive to its users because this is the unique identifier for the library used by the Arduino development software command line interfaces, sketch metadata, library dependencies, and installation location.

If you wish to change the name it will need to be done manually by request:

  1. Change the name value in the library.properties file and update the version.
  2. Create a release or tag.
  3. Open an issue here specifying the URL of the library's repository.

Limitations

Is my Git repository OK?

Your repo is OK if it meets all the requirements listed here.

Are Git submodules supported?

No. The library archive distributed by Library Manager will only contain an empty folder where the submodule should be.

Usage

Can I add my own URL with my own library index?

No. At the moment, the Arduino development software handles one URL only, and that's written into the code (dev jargon: it's hardcoded), this is a known limitation. However, if you know your way through the code, you can change that URL with another one.

When I install a library that I know depends on another library, will this other library be installed as well?

As of Arduino IDE 1.8.10 and Arduino CLI 0.7.0, you can specify the dependencies of a library in the depends field of library.properties. Those libraries can be installed automatically when someone installs that library via Library Manager.

For more information, see the library.properties file format documentation.

Can I install multiple versions of one library and use the proper one in my sketches?

Library Manager installs libraries into your sketchbook's libraries folder. Since you cannot create two folders with the same name, we can't install two versions of the same library. However, you can switch between library versions by selecting the appropriate one from the version dropdown that pops up on Library Manager when more than one version is available.

How can I remove a library I installed via Library Manager?

Arduino IDE 2.x

Hover the mouse pointer over the INSTALLED label on the library listing in Library Manager. It will now change to UNINSTALL, which you can click to uninstall that library.

Classic Arduino IDE

This version of the Arduino IDE does not have an integrated uninstall functionality, so you will need to remove the library manually. Open your sketchbook's libraries folder with your operating system's file explorer (Windows: Explorer, Mac: Finder, Linux: Nautilus, kfiles...) and delete the folder containing the library.

Arduino CLI

Libraries can be uninstalled via the arduino-cli lib uninstall command.

Security & Malware Reporting

If you think you found a vulnerability, malware or other security-related defect in any Arduino Library projects, please take a look at our security policy and report it to our Security Team 🛡️.

Thank you!

E-mail contact: security@arduino.cc