Update versioning spec

docs/SUMMARY.md

@@ -19,6 +19,7 @@
 - [Flags](flags.md)
 - [URLs](url.md)
 - [Namespaces](namespaces.md)
+- [Versioning](versioning.md)
 
 # Packaging
 

docs/schema/addon.md

@@ -5,7 +5,8 @@
   "addonscript": {},
   "id": "myaddon",
   "namespace": "com.example",
-  "version": "1.0.0",
+  "version": "1.0",
+  "semver": "1.0.0",
   "files": [],
   "relations": [],
   "flags": ["server", "client"],
@@ -28,11 +29,15 @@ It should be written in the `kebab-case` format, meaning lowercase only and usin
 
 ### version
 
-This is the version number of this version. It must follow [semver versioning specifications](https://semver.org/spec/v2.0.0.html),
-as they are used to compare versions.
+This is the version number of this version. Versions are compared by [Maven version order rules](../versioning.md#version-order-specification).
+If this version number is valid semver, the `semver` property is implicitly equal to `version` if it was not explicitly set.
 
 ## 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).
+
 ### namespace
 
 The namespace of the addon in a reverse-DNS format. Used to identify addons across repositories, if it is present.

docs/schema/relation.md

@@ -3,7 +3,7 @@
 ```json
 {
   "id": "namespace:othermod",
-  "version": "1.0",
+  "version": "[1.0]",
   "repositories": ["repo1"],
   "flags": [],
   "conditions": {}
@@ -16,13 +16,17 @@
 
 This is the ID or namespaced ID of the addon this relation refers to.
 
+## Optional properties
+
 ### version
 
-<!--TODO: update link one PR is merged-->
+This is a [maven version range](../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 has to be set.
+
+### semver
 
 This is a [semver version range](https://github.com/semver/semver/pull/584) of supported versions of this relation.
-
-## Optional properties
+It will only allow versions of the related addon, which have a valid semver version number, which is in this range.
 
 ### repositories
 

docs/versioning.md

@@ -0,0 +1,66 @@
+# 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 may only contain non-space ASCII characters.
+
+## Maven Versioning Specification
+
+### Version Order Specification
+
+The Maven coordinate is split in tokens between dots ('`.`'), hyphens ('`-`') and transitions between digits and characters. The separator is recorded and will have effect on the order. A transition between digits and characters is equivalent to a hyphen. Empty tokens are replaced with "`0`". This gives a sequence of version numbers (numeric tokens) and version qualifiers (non-numeric tokens) with "`.`" or "`-`" prefixes.
+
+Splitting and Replacing Examples:
+
+- `1-1.foo-bar1baz-.1` -> `1-1.foo-bar-1-baz-0.1`
+
+Then, starting from the end of the version, the trailing "null" values (`0`, `""`, "`final`", "`ga`") are trimmed. This process is repeated at each remaining hyphen from end to start.
+
+Trimming Examples:
+
+- `1.0.0` -> `1`
+- `1.ga` -> `1`
+- `1.final` -> `1`
+- `1.0` -> `1`
+- `1.` -> `1`
+- `1-` -> `1`
+- `1.0.0-foo.0.0` -> `1-foo`
+- `1.0.0-0.0.0` -> `1`
+
+The version order is the `lexicographical order` on this sequence of prefixed tokens, the shorter one padded with enough "null" values with matching prefix to have the same length as the longer one. Padded "null" values depend on the prefix of the other version: 0 for '.', "" for '-'. The prefixed token order is:
+
+- if the prefix is the same, then compare the token:
+    - Numeric tokens have the natural order.
+    - Non-numeric tokens ("qualifiers") have the alphabetical order, except for the following tokens which come first in this order:
+"`alpha`" < "`beta`" < "`milestone`" < "`rc`" = "`cr`" < "`snapshot`" < "" = "`final`" = "`ga`" < "`sp`"
+        - the "`alpha`", "`beta`" and "`milestone`" qualifiers can respectively be shortened to "a", "b" and "m" when directly followed by a number.
+- else "`.qualifier`" < "`-qualifier`" < "`-number`" < "`.number`"
+
+
+End Result Examples:
+
+- "`1`" < "`1.1`" (number padding)
+- "`1-snapshot`" < "`1`" < "`1-sp`" (qualifier padding)
+- "`1-foo2`" < "`1-foo10`" (correctly automatically "switching" to numeric order)
+- "`1.foo`" < "`1-foo`" < "`1-1`" < "`1.1`"
+- "`1.ga`" = "`1-ga`" = "`1-0`" = "`1.0`" = "`1`" (removing of trailing "null" values)
+- "`1-sp`" > "`1-ga`"
+- "`1-sp.1`" > "`1-ga.1`"
+- "`1-sp-1`" < "`1-ga-1`" = "`1-1`" (trailing "null" values at each hyphen)
+- "`1-a1`" = "`1-alpha-1`"
+
+Note: Contrary to what was stated in some design documents, for version order, snapshots are not treated differently than releases or any other qualifier.
+
+### Dependancy Version Requirement Specification
+
+Version requirements have the following syntax:
+
+- `1.0`: Soft requirement for 1.0. Use 1.0 if no other version appears earlier in the dependency tree.
+- `[1.0]`: Hard requirement for 1.0. Use 1.0 and only 1.0.
+- `(,1.0]`: Hard requirement for any version <= 1.0.
+- `[1.2,1.3]`: Hard requirement for any version between 1.2 and 1.3 inclusive.
+- `[1.0,2.0)`: 1.0 <= x < 2.0; Hard requirement for any version between 1.0 inclusive and 2.0 exclusive.
+- `[1.5,)`: Hard requirement for any version greater than or equal to 1.5.
+- `(,1.0],[1.2,)`: Hard requirement for any version less than or equal to 1.0 than or greater than or equal to 1.2, but not 1.1. Multiple requirements are separated by commas.
+- `(,1.1),(1.1,)`: Hard requirement for any version except 1.1; for example because 1.1 has a critical vulnerability.
+
+Maven picks the highest version of each project that satisfies all the hard requirements of the dependencies on that project. If no version satisfies all the hard requirements, the build fails.