[skip changelog] Document library dependency version constraints #1786
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Arduino libraries may specify dependencies on other libraries in their metadata. The Arduino Library Manager offers the option to install these dependencies when the user installs the library. By default, the latest version of the dependency is installed. However, libraries may be compatible or tested working only with specific versions of a dependency. In this case, the library developer may wish to specify a particular version or version range of the dependency. Arduino CLI and the Arduino Library index system has had support for such dependency version constraints for the last 2.5 years, but it was never documented so has only been used by the few library developers who discovered it via other means. The dependencies version constraint system is hereby fully documented in the Arduino library specification. This will allow meaningful benefit to finally come from the work done to add this valuable capability.
per1234
added
topic: documentation
|
The failure of the link check is expected due to there not having been a release since the Mac ARM 64 bit build target was added to the release links table. |
umbynos
approved these changes
Jun 28, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Please check if the PR fulfills these requirements
before creating one)
our contributing guidelines
UPGRADING.mdhas been updated with a migration guide (for breaking changes)What kind of change does this PR introduce?
Documentation update.
What is the current behavior?
Arduino libraries may specify dependencies on other libraries in their metadata. The Arduino Library Manager offers the option to install these dependencies when the user installs the library.
By default, the latest version of the dependency is installed. However, libraries may be compatible or tested working only with specific versions of a dependency. In this case, the library developer may wish to specify a particular version or version range of the dependency.
Arduino CLI and the Arduino Library index system has had support for such dependency version constraints for the last 2.5 years, but it was never documented so has only been used by the few library developers who discovered it via other means.
What is the new behavior?
The dependencies version constraint system is fully documented in the Arduino library specification. This will allow meaningful benefit to finally come from the work done to add this valuable capability.
Does this PR introduce a breaking change, and is titled accordingly?
No breaking changes.
Other information:
I had to resort to some unusual markup in order to produce a syntax table that would be formatted correctly by the Prettier formatter (which expects the escaped pipe
\|approach supported by the "GitHub Flavored Markdown" dialect) and also rendered correctly in the MkDocs/Python-Markdown-produced website (which faithfully adheres to the original Markdown specification, and so does not recognize the pipe escaping syntax): mkdocs/mkdocs#2761Version constraints documentation from the
go.bug.st/relaxed-semverpackage that provides this capability to Arduino CLI: https://github.com/bugst/relaxed-semver#version-constraintsVersion constraints are not supported by Arduino IDE 1.x (it always installs the latest version of the dependency after user confirmation), and older versions of Arduino CLI and Arduino IDE 2.x. I have documented the cutoff versions in the specification. The specific points in the development history are:
go.bug.st/relaxed-semver: bugst/relaxed-semver@a3a14e5