From d8f30c0316ef411b1ea4507ebf5cc12e5662dee3 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 14 Apr 2021 00:28:23 -0700 Subject: [PATCH] Document policy re: who can add libraries to Library Manager 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. --- FAQ.md | 31 +++++++++++++++++++++---------- README.md | 2 +- 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/FAQ.md b/FAQ.md index b81c67c82..8b8b5063f 100644 --- a/FAQ.md +++ b/FAQ.md @@ -8,14 +8,15 @@ - [What is the Arduino Library Manager?](#what-is-the-arduino-library-manager) - [How is the Library Manager index generated?](#how-is-the-library-manager-index-generated) - [Submission](#submission) - - [How can I add my library to Library Manager?](#how-can-i-add-my-library-to-library-manager) + - [How can I add a library to Library Manager?](#how-can-i-add-a-library-to-library-manager) - [What are the requirements for a library to be added to Library Manager?](#what-are-the-requirements-for-a-library-to-be-added-to-library-manager) + - [Who is allowed to add a library to Library Manager?](#who-is-allowed-to-add-a-library-to-library-manager) - [Updates](#updates) - [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) - [What are the requirements for publishing new releases of libraries already in the Library Manager list?](#what-are-the-requirements-for-publishing-new-releases-of-libraries-already-in-the-library-manager-list) - [Why aren't releases of my library being picked up by Library Manager?](#why-arent-releases-of-my-library-being-picked-up-by-library-manager) - [I did something wrong! How can I change or unpublish an already published library?](#i-did-something-wrong-how-can-i-change-or-unpublish-an-already-published-library) - - [How can I change my library's name?](#how-can-i-change-my-librarys-name) + - [How can I change a library's name?](#how-can-i-change-a-librarys-name) - [Limitations](#limitations) - [Is my Git repository OK?](#is-my-git-repository-ok) - [Are Git submodules supported?](#are-git-submodules-supported) @@ -58,7 +59,9 @@ Every hour, the automated Library Manager indexer system: ## Submission -### How can I add my library to Library Manager? +### How can I add a library to Library Manager? + + Follow the instructions [here](README.md#adding-a-library-to-library-manager). @@ -86,15 +89,21 @@ Arduino Lint is also available as a GitHub Actions action that can be used in th 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](#update-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](#update-requirements). -1. Update the `version` in your [`library.properties`](https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata)). -1. Tag your library once more and push the new tag (or create a release if your Git-hosting site offers a way to do it, for example with [GitHub "releases"](https://help.github.com/articles/creating-releases/)). +1. Update the `version` in the library's [`library.properties`](https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata)). +1. 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"](https://help.github.com/articles/creating-releases/)). -[Our indexer](#how-is-the-library-manager-index-generated) checks for new releases every hour and will eventually fetch and publish your new release. +[Our indexer](#how-is-the-library-manager-index-generated) 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? @@ -116,15 +125,17 @@ In order to **un**publish a library version, delete its related tag/release. Once you have done that, open an issue in [the issue tracker of this repository](https://github.com/arduino/library-registry/issues), specifying the URL of the library repository and requesting that the library be updated. -### How can I change my library's name? +### 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](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_lib/), sketch [metadata](https://arduino.github.io/arduino-cli/latest/sketch-specification/#metadata), library [dependencies](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format), 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 your [library.properties file](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) and update the `version`. +1. Change the `name` value in the [library.properties file](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) and update the `version`. 1. Create a release or tag. -1. Submit an [issue report](https://github.com/arduino/library-registry/issues) requesting the name be changed and stating the URL of your library's repository. +1. Submit an [issue report](https://github.com/arduino/library-registry/issues) requesting the name be changed and stating the URL of the library's repository. ## Limitations @@ -145,7 +156,7 @@ However, if you know your way through the code, you can change that URL with ano ### 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 your library in the `depends` field of library.properties. Those libraries can be installed automatically when someone installs your library via Library Manager. +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](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format). diff --git a/README.md b/README.md index efbf66f9f..0501ed78a 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ For more information about Arduino Library Manager and how the index is maintain ## Adding a library to Library Manager -If you would like to have your library available for installation via Library Manager, just submit a +If you would like to make a library available for installation via Library Manager, just submit a [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) that adds the repository URL to [the list](repositories.txt). You are welcome to add multiple libraries at once.