From 2e26c5ab95c6fdcfc82d01c929be3227a632ee30 Mon Sep 17 00:00:00 2001 From: Timo Ley Date: Sat, 13 Nov 2021 20:47:21 +0100 Subject: [PATCH] Spec overhaul --- docs/SUMMARY.md | 9 +++++---- docs/schema/index.md | 25 ------------------------ docs/schema/meta.md | 28 +++++++++++++++++++++----- docs/schema/relation.md | 9 ++++++++- docs/schema/repository.md | 5 +++-- docs/schema/root.md | 41 ++++++++++++++++++++++++--------------- docs/schema/version.md | 37 ----------------------------------- docs/url.md | 4 ++-- 8 files changed, 66 insertions(+), 92 deletions(-) delete mode 100644 docs/schema/index.md delete mode 100644 docs/schema/version.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index f03a6c3..e4461d1 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -5,17 +5,18 @@ # Schema - [Addon Object](schema/root.md) - [AddonScript Object](schema/addonscript.md) - - [Version Object](schema/version.md) - - [File Object](schema/file.md) - - [Relation Object](schema/relation.md) + - [File Object](schema/file.md) + - [Install Object](schema/install.md) + - [Relation Object](schema/relation.md) + - [Conditions Object](schema/conditions.md) - [Repository Object](schema/repository.md) - - [Index Object](schema/index.md) - [Meta Object](schema/meta.md) # Concepts - [Installing](install.md) - [Flags](flags.md) - [URLs](url.md) +- [Namespaces](namespaces.md) # Packaging - [Packaging](packaging/README.md) diff --git a/docs/schema/index.md b/docs/schema/index.md deleted file mode 100644 index ec97760..0000000 --- a/docs/schema/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# Index Object - -```json -{ - "versions": { - "1.0": "https://example.json/mymod-1.0.json" - }, - "addons": { - "othermod": "https://example.com/othermod.json" - } -} -``` - -## Optional Properties - -### versions - -This is an object, with version numbers as keys and [URLs](../url.md) to AddonScript files as values. The AddonScript file which the URL -points to must include the version number, which is the key in the map, and its addon ID must match the addon ID of the AddonScript -file which includes the index object. - -### addons - -This is an object, with addon IDs as keys and [URLs](../url.md) to AddonScript files as values. The addon ID of the AddonScript file, to -which the URL points, must match the key in the map. diff --git a/docs/schema/meta.md b/docs/schema/meta.md index 12ff292..c1664c1 100644 --- a/docs/schema/meta.md +++ b/docs/schema/meta.md @@ -1,7 +1,25 @@ # Meta Object -Meta objects can be included in [addon](root.md) and [version](version.md) objects. -They should be used to give information about the addon or the version, like a **name**, -a **description** or a **changelog**. The specification does not require a specific format -for meta objects, therefore you can add any property to it. -It is however recommended to follow conventions for it. +``` json +{ + "addon": { + "name": "My cool addon name", + "icon": "./icon.png", + "description":"./README.md", + "summary": "My Addon", + "website": "https://example.com", + "source": "https://gitea.com/user/myaddon", + "issues": "https://gitea.com/user/myaddon/issues", + "contributors": ["Alice", "Bob"] + }, + "version": { + "changelog": "./CHANGELOG.md", + "timestamp": 1594753200 + }, + "additional": {} +} +``` + +## Optional properties + + diff --git a/docs/schema/relation.md b/docs/schema/relation.md index 7e38f94..6a9128f 100644 --- a/docs/schema/relation.md +++ b/docs/schema/relation.md @@ -4,6 +4,7 @@ { "id": "namespace:othermod", "version": "[1.0,)", + "repositories": ["repo1"], "flags": [], "conditions": {} } @@ -17,10 +18,16 @@ This is the ID or namespaced ID of the addon this relation refers to. ### version -This is a [maven version range](https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html) of supported versions of this relation. +This is a [semver version range](https://github.com/semver/semver/pull/584) of supported versions of this relation. ## Optional properties +### repositories + +This is an array of [repository](repository.md) IDs. This are the repositories, from where AddonScript should try to get this relation from, +in the order as they are ordered in the array. If this property is not set or the array is empty, AddonScript will try to resolve the relation by +the namespace from all defined repositories. + ### flags This is an array of [flags](../flags.md) for this relation. If this property is not present in a relation object, the relation diff --git a/docs/schema/repository.md b/docs/schema/repository.md index e8b1a64..03698fd 100644 --- a/docs/schema/repository.md +++ b/docs/schema/repository.md @@ -16,10 +16,11 @@ This is the ID of the repository. It has to be unique to the AddonScript file. ### type -This is the type of the repository. Possible values are [`api`](../repository/api/README.md) or [`maven`](../repository/maven.md). +This is the type of the repository. Possible values are [`api`](../repository/api/README.md), [`maven`](../repository/maven.md) or [`index`](../repository/index.md). ### url This is the base URL of the repository. While other URLs in AddonScript can have different schemes, -the base URL has to be a http(s) URL. If it is a maven repository the scheme can also be `file`, where +the base URL has to be a http(s) URL, except for `index` and `maven` repositories, where it can also be `file`. +If it is a maven repository the scheme can also be `file`, where it points to a directory, which contains the maven repository. diff --git a/docs/schema/root.md b/docs/schema/root.md index d992c37..87dce01 100644 --- a/docs/schema/root.md +++ b/docs/schema/root.md @@ -4,10 +4,12 @@ { "addonscript": {}, "id": "myaddon", - "versions": [], + "namespace": "com.example", + "version": "1.0", + "files": [], + "relations": [], + "flags": ["server", "client"], "repositories": [], - "index": {}, - "flags": {}, "meta": {} } ``` @@ -20,29 +22,36 @@ This is an [AddonScript object](addonscript.md) containing information about the ### id -This is the ID of your addon. It should only contain **lowercase letters, numbers and dashes**. +This is the ID of the addon. It should only contain **lowercase letters, numbers and dashes**. + +### version + +This is the version number of this version. It must follow [semver version naming conventions](https://semver.org/spec/v2.0.0.html), +as they are used to compare versions. ## Optional properties -### versions +### namespace -This is an array of [version objects](version.md). It is possible to define multiple versions of the addon in one AddonScript file, -but in the most cases there should be just one version per file. Athough this property is optional, as you can define versions -in the [index](index.md), it can be used to define a list of versions, which can be found in the index. +This is the namespace of the addon. + +### files + +This is an array of [file objects](file.md) including the files belonging to this version. + +### relations + +This is an array of [relation objects](relation.md) which represents related addons. + +### flags + +This is an array of [flags](../flags.md) for this version. ### repositories This is an array of [repository objects](repository.md). Each repository object defines one repository from which files or addons can be retrieved. -### index - -This is an [index object](index.md) which includes links to other versions of this addon, or to other related addons. - -### flags - -Not yet specified - ### meta This is a [meta object](meta.md). diff --git a/docs/schema/version.md b/docs/schema/version.md deleted file mode 100644 index 8c83fd0..0000000 --- a/docs/schema/version.md +++ /dev/null @@ -1,37 +0,0 @@ -# Version Object - -```json -{ - "version": "1.0", - "files": [], - "relations": [], - "flags": ["server", "client"], - "meta": {} -} -``` - -## Required properties - -### version - -This is the version number of this version. It should follow [maven version naming conventions](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm), -as they are used to comparing versions. - -## Optional properties - -### files - -This is an array of [file objects](file.md) including the files belonging to this version. - -### relations - -This is an array of [relation objects](relation.md) which represents related addons. - -### flags - -This is an array of [flags](../flags.md) for this version. If this property is not present in a version object, the version -will have the flags which are set as default for versions. - -### meta - -This is a [meta object](meta.md). diff --git a/docs/url.md b/docs/url.md index 07e7f7a..f8095c4 100644 --- a/docs/url.md +++ b/docs/url.md @@ -18,7 +18,7 @@ In this example `com.example` it the namespace of the artifact, `someartifact` i `mvn://com.example/someartifact/1.0.jar` would also be a valid URL without an optional specifier. ## file -```file://relative/path/to/file.jar``` +```./relative/path/to/file.jar``` -This URL scheme is a relative path to a file. It can only be used with [packaging](packaging/README.md) +This is a relative path to a file. It can only be used with [packaging](packaging/README.md) or in some third-party environments, which are not covered by this specification.