tilera
/
addonscript-spec
forked from addonscript/addonscript-spec
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request 'Versioning spec improvements' (#26) from tilera/addonscript-spec:versioning into master 

Reviewed-on: addonscript/addonscript-spec#26
This commit is contained in:
Timo Ley 2022-09-17 13:04:40 +00:00
parent c170119e80 1861e66548
commit 30545bf09e
3 changed files with 30 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
docs/concepts/versioning.md
View File

@ -1,7 +1,28 @@
# AddonScript Versioning
Version numbers in AddonScript are based on Maven version numbers. The only difference to the Maven versioning specification is,
that AddonScript version numbers MUST only contain non-space ASCII characters.
## AddonScript Version Numbers
AddonScript version numbers MUST only contain non-whitespace ASCII characters. They SHOULD follow the
[SemVer specifications](https://semver.org/spec/v2.0.0.html). AddonScript version numbers are ordered
according to the [Maven version order specification](#version-order-specification).
### SemVer Compatible Versions
If an AddonScript version number is valid SemVer, that version of the addon is SemVer compatible and implies
all semantics according to SemVer. AddonScript implementations MAY provide specific behavior based on the
semver semantics, for example warning the user before updating to a next major version.
## AddonScript Version Ranges
An AddonScript version range can either be a [SemVer version range](https://github.com/semver/semver/pull/584)
or a [Maven version range](#dependency-version-requirement-specification). If a version range starts with one
of SemVer primitive operators (`<`, `<=`, `>`, `>=`, `=`) it will be considered as a SemVer version range,
otherwise it will be a Maven version range. SemVer version ranges can only include
[SemVer compatible versions](#semver-compatible-versions). If the version range is required to include
an exact version, for example when using the `included` [relational flag](./flags.md#relational-flags),
it MUST be a Maven version range, which is the targeted version surrounded by `[]`. In all other cases
it is highly RECOMMENDED to use SemVer version ranges, as long as the targeted addon uses
[SemVer compatible versions](#semver-compatible-versions).
## Maven Versioning Specification

11
docs/schema/manifest.md
View File

@ -5,8 +5,7 @@
"addonscript": {},
"id": "myaddon",
"namespace": "com.example",
"version": "1.0",
"semver": "1.0.0",
"version": "1.0.0",
"files": [],
"relations": [],
"flags": {},
@ -30,9 +29,7 @@ It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD b
### version
This is the [version number](../concepts/versioning.md) of this version. Versions are compared by
[Maven version order rules](../concepts/versioning.md#version-order-specification).
If this version number is valid semver, the `semver` property is implicitly equal to `version` if `semver` was not explicitly set.
This is the [AddonScript version number](../concepts/versioning.md#addonscript-version-numbers) of this version.
### namespace
@ -44,10 +41,6 @@ This is an [flags object](flags.md) which contains [manifest flags](../concepts/
## Optional properties
### semver
This is the version number of this version in semver format. It MUST follow the [semver versioning specifications](https://semver.org/spec/v2.0.0.html).
### files
This is an array of [file objects](file.md) including the files belonging to this addon.

15
docs/schema/relation.md
View File

@ -16,6 +16,11 @@
This is the ID of the addon this relation refers to.
### version
This is an [AddonScript version range](../concepts/versioning.md#addonscript-version-ranges) that specifies, which versions
of the related addon are targeted by this relation.
## Optional properties
### namespace
@ -23,16 +28,6 @@ This is the ID of the addon this relation refers to.
This is the [namespace](../concepts/namespaces.md) of the related addon. This property will be implicitly equal to the
[namespace of the addon](manifest.md#namespace), if it was not set explicitly.
### version
This is a [maven version range](../concepts/versioning.md#dependancy-version-requirement-specification) that specifies, which versions
of the related addon are targeted by this relation. You can either set this property or `semver`, but exactly one of them MUST be set.
### semver
This is a [semver version range](https://github.com/semver/semver/pull/584) of supported versions of this relation.
It will only allow versions of the related addon, which have a valid semver version number, which is in this range.
### repositories
This is an array of [repository](repository.md) IDs. These are the repositories, from which AddonScript will try to get this relation from,