arduino/library-registry
1
0
Fork 0
mirror of https://github.com/arduino/library-registry.git synced 2025-04-20 14:47:46 +03:00
Code

Consolidate list of requirements in FAQ

Browse Source 
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.
This commit is contained in:
per1234 2021-04-09 04:35:40 -07:00
parent 616c3b5110
commit beb45f13df
2 changed files with 37 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
FAQ.md
View File

@ -5,23 +5,22 @@
The Arduino Library Manager is a feature of the Arduino IDE (**Sketch > Include Library > Manage Libraries...**) which makes it easy for users to find, install, and update both official and 3rd party libraries. When your library is added to the library list, every release/tag version of the library in your repository will automatically be made available for installation via Library Manager. The 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: <br /> The Arduino Library Manager is a feature of the Arduino IDE (**Sketch > Include Library > Manage Libraries...**) which makes it easy for users to find, install, and update both official and 3rd party libraries. When your library is added to the library list, every release/tag version of the library in your repository will automatically be made available for installation via Library Manager. The 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: <br />
https://www.arduino.cc/en/Guide/Libraries#toc3 https://www.arduino.cc/en/Guide/Libraries#toc3
### How is the library list generated?
From a list of public Git repos, a job (a small program that runs regularly) fetches every tag, verifies library files and pushes the updated [list](http://downloads.arduino.cc/libraries/library_index.json) onto the Arduino download server. ### What are the requirements for a library to be added to the Library Manager index?
Only valid libraries and their tags are published.
A library is **not valid** when: <a id="submission-requirements"></a>
- it's not in [1.5 format](https://arduino.github.io/arduino-cli/latest/library-specification) and in particular it misses a [library.properties](https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata) file (1.5 format folder layout is not required) - [ ] The library must be fully compliant with the [Arduino Library Specification](https://arduino.github.io/arduino-cli/latest/library-specification).
- its `name` field in library.properties starts with `Arduino` - [ ] The library must have [a library.properties file](https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata), in compliance with the Arduino Library 1.5 format.
- its `url` field in library.properties is left blank - [ ] The library.properties file must be located in the root of the repository.
- its version number is not [semver compliant](http://semver.org/) - [ ] The library must not have the same library.properties `name` value (regardless of case) as another library previously added to the Library Manager index.
- it contains `.exe` files - [ ] For 3rd party libraries, the `name` field in library.properties must not start with `Arduino`.
- it contains a `.development` file - [ ] The library repository must not contain any `.exe` files.
- it contains symlinks - [ ] The library repository must not contain a [`.development` file](https://arduino.github.io/arduino-cli/latest/library-specification/#development-flag-file).
- our antivirus finds infected files - [ ] The library repository must not contain any [symlinks](https://en.wikipedia.org/wiki/Symbolic_link).
- [ ] The library repository must not contain any files detected as infected by our antivirus scan.
**The job runs every hour. If a new library has been released, you can expect it to be listed within the hour, but it might take longer**. - [ ] The library repository must have a [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) (or [release](https://help.github.com/articles/creating-releases/)) 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: Arduino has created a command line tool to check libraries for compliance with all the Library Manager requirements:
@ -31,21 +30,33 @@ Arduino Lint is also available as a GitHub Actions action that can be used in th
https://github.com/arduino/arduino-lint-action https://github.com/arduino/arduino-lint-action
### How is the library list generated?
From a list of public Git repos, a job (a small program that runs regularly) fetches every tag, checks compliance with [the requirements](#requirements), and pushes the updated [list](http://downloads.arduino.cc/libraries/library_index.json) onto the Arduino download server.
Only valid libraries and their tags are published.
**The job runs every hour. If a new library has been released, you can expect it to be listed within the hour, but it might take longer**.
### How can I add my library to Library Manager? ### How can I add my library to Library Manager?
- Your library repository must be hosted on a major Git-hosting website like GitHub, BitBucket or GitLab (other hosting sites may be considered on request). Follow the submission instructions [here](README.md#adding-a-library-to-library-manager).
- Ensure your library is compliant with [1.5 format](https://arduino.github.io/arduino-cli/latest/library-specification/) (1.5 format folder layout is not required)
- Your library must not have the same library.properties `name` value (regardless of case) as another library previously added to the Library Manager index.
- [Tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) it and push the tag (or create a release if you web hosting offers a way to do it, for example with [GitHub "releases"](https://help.github.com/articles/creating-releases/))
- Follow the submission instructions [here](README.md#adding-a-library-to-library-manager).
Shortly after the pull request is merged by the automated system, your library will be available for installation via Library Manager.
### How can I publish a new release once my library is in the list? ### How can I publish a new release once my library is in the list?
Ensure you've changed version in your `library.properties`. Then tag your library once more and push the new tag (or create a release if your web hosting offers a way to do it, for example with GitHub "releases"). 1. Make sure the library is compliant with [all requirements](#update-requirements).
1. Update the `version` in your `library.properties`.
1. Tag your library once more and push the new tag (or create a release if your web hosting 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 your new release. Our indexer checks for new releases every hour and will eventually fetch and publish your new release.
### What are the requirements for publishing new releases of libraries already in the Library Manager index?
<a id="update-requirements"></a>
- [ ] The library must be compliant with all the same [requirements that apply to submissions](#submission-requirements).
- [ ] 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](#how-can-i-change-my-librarys-name).
- [ ] The `version` property in library.properties must not be the same as it was in a tag previously added to the Library Manager index.
### Sorry, I did something wrong! How can I change or unpublish an already published library? ### Sorry, I did something wrong! How can I change or unpublish an already published library?
In order to change contents of an already published library version, you can recreate its related tag. In order to change contents of an already published library version, you can recreate its related tag.
@ -56,11 +67,7 @@ Once you have done that, open an issue in [the issue tracker of this repository]
### Why aren't releases of my library being picked up by Library Manager? ### Why aren't releases of my library being picked up by Library Manager?
The Library Manager indexer job will not pick up releases which don't have a unique `version` value in library.properties. Remember to always update the `version` value in your library.properties _before_ creating the tag or release. The Library Manager indexer job will reject any releases which aren't compliant with all [the requirements](#update-requirements).
Make sure your library meets all the requirements listed [here](#how-is-the-library-list-generated).
Changing the `name` value in your library.properties from the one it had at the time when the library was added to the Library Manager index will cause releases to be ignored. You need to request a name change, as explained [here](#how-can-i-change-my-librarys-name).
### How can I change my library's name? ### How can I change my library's name?
@ -82,7 +89,7 @@ No, we don't have a delete button. Libraries managed by the Library Manager are
### Is my Git repo OK? ### Is my Git repo OK?
Your repo is OK if its root folder contains the file `library.properties` and the rest of the library source code. If your library is stored in a subfolder, your repo is not OK and we can't include your library in the list. Your repo is OK if it meets all [the requirements listed here](#submission-requirements).
### Are Git submodules supported? ### Are Git submodules supported?

4
README.md
View File

@ -18,7 +18,7 @@ See the instructions below for detailed instructions on how to do this via the G
### Instructions ### Instructions
1. You may want to first take a look at 1. You may want to first take a look at
[the requirements for admission into the Arduino Library Manager index](FAQ.md). Each submission will be checked for [the requirements for admission into the Arduino Library Manager index](FAQ.md#submission-requirements). Each submission will be checked for
compliance before being accepted. compliance before being accepted.
1. Open this link to [fork](https://guides.github.com/activities/forking/) this repository and edit the list via the 1. Open this link to [fork](https://guides.github.com/activities/forking/) this repository and edit the list via the
GitHub web interface: https://github.com/arduino/library-registry/edit/main/repositories.txt GitHub web interface: https://github.com/arduino/library-registry/edit/main/repositories.txt
@ -75,7 +75,7 @@ description, making it clear that the URL is intentionally being removed.
## Report a problem with Library Manager ## Report a problem with Library Manager
Please first take a look at [the FAQ](FAQ.md). If a library release is missing from Library Manager, it is usually Please first take a look at [the FAQ](FAQ.md). If a library release is missing from Library Manager, it is usually
because it was not compliant with all the requirements listed in that document. because it was not compliant with all [the requirements](FAQ.md#update-requirements) listed in that document.
This repository is not an appropriate place to request support or report problems with a library. Check the library's This repository is not an appropriate place to request support or report problems with a library. Check the library's
own documentation for instructions or ask on the [Arduino Forum](https://forum.arduino.cc/). own documentation for instructions or ask on the [Arduino Forum](https://forum.arduino.cc/).