From c304c628553a80efdae21766b953a4731cc5ad75 Mon Sep 17 00:00:00 2001 From: Timo Ley Date: Mon, 5 Sep 2022 16:54:36 +0200 Subject: [PATCH] Spec rephrasing to use requirement keywords --- docs/api/README.md | 2 +- docs/api/features/addons.md | 4 ++-- docs/api/features/files.md | 8 ++++---- docs/concepts/flags.md | 10 +++++----- docs/concepts/install.md | 7 +++---- docs/concepts/instance.md | 12 ++++++------ docs/concepts/links.md | 2 +- docs/concepts/namespaces.md | 12 ++++++------ docs/concepts/versioning.md | 2 +- docs/packaging/zip.md | 2 +- docs/schema/api_addon.md | 2 +- docs/schema/api_file.md | 6 +++--- docs/schema/file.md | 10 +++++----- docs/schema/install.md | 2 +- docs/schema/manifest.md | 4 ++-- docs/schema/meta.md | 11 ++++++----- docs/schema/relation.md | 6 +++--- docs/schema/repository.md | 2 +- 18 files changed, 52 insertions(+), 52 deletions(-) diff --git a/docs/api/README.md b/docs/api/README.md index 4bb75f0..8249d96 100755 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -30,7 +30,7 @@ available on this API instance. ## Features API features can be either part of the specification itself or -are specified by third parties. Third-party API features should +are specified by third parties. Third-party API features SHOULD be in a namespace-like format (reversed domain name). These API features are part of the AddonScript specification itself: diff --git a/docs/api/features/addons.md b/docs/api/features/addons.md index 37ecf61..711f03d 100644 --- a/docs/api/features/addons.md +++ b/docs/api/features/addons.md @@ -18,7 +18,7 @@ of the addon. #### Responses: - `200 OK`: The addon is available in this addon repository. -The response body must be an [API Addon Object](../../schema/api_addon.md). +The response body MUST be an [API Addon Object](../../schema/api_addon.md). - `404 Not Found`: The addon is not available in this addon repository. ### Get addon manifest @@ -36,5 +36,5 @@ This endpoint can be used to retrieve the manifest of a specific version of an a #### Responses: - `200 OK`: This version of the addon is available in this addon repository. -The response body must be an [Addon Manifest](../../schema/manifest.md). +The response body MUST be an [Addon Manifest](../../schema/manifest.md). - `404 Not Found`: This version of the addon is not available in this addon repository. \ No newline at end of file diff --git a/docs/api/features/files.md b/docs/api/features/files.md index 0065d5f..1d1e203 100644 --- a/docs/api/features/files.md +++ b/docs/api/features/files.md @@ -7,7 +7,7 @@ `GET {base URL}/v2/files/:namespace/:addon/:version/:qualifier` This endpoint can be used to retrieve information about a specific file. -If the instance don't know this file, it must respond with status code 404. +If the instance don't know this file, it MUST respond with status code 404. #### Path variables: @@ -20,7 +20,7 @@ of the addon to which the file belongs to #### Responses: - `200 OK`: The file is available in this file repository. -The response body must be an [API File Object](../../schema/api_file.md). +The response body MUST be an [API File Object](../../schema/api_file.md). - `404 Not Found`: The file is not available in this file repository. ### Get a file by hash @@ -29,7 +29,7 @@ The response body must be an [API File Object](../../schema/api_file.md). This endpoint can be used to retrieve information about a file from the hash value of the file. If the instance can't find the file by the hash or does not know the specified hash algorithm, -it must respond with status code 404. +it MUST respond with status code 404. #### Path variables: @@ -39,6 +39,6 @@ it must respond with status code 404. #### Responses: - `200 OK`: The file is available in this file repository. -The response body must be an [API File Object](../../schema/api_file.md). +The response body MUST be an [API File Object](../../schema/api_file.md). - `404 Not Found`: The file is either not available in this file repository or the hash algorithm is unknown to the API instance. \ No newline at end of file diff --git a/docs/concepts/flags.md b/docs/concepts/flags.md index 2664ab4..51a6813 100644 --- a/docs/concepts/flags.md +++ b/docs/concepts/flags.md @@ -23,10 +23,10 @@ addon manifest, including for which side it is available and for which side it i - `required` This flag specifies, that the related addon or file is required for the addon. If the addon gets installed, than any relation or file, which has this flag set, also has to be installed. - `optional` This flag specifies, that the related addon or file is optional for this addon. If the addon gets installed, - the user should be able to choose, whether he wants to install the relation or file with this flag, or not. + the user SHOULD be able to choose, whether he wants to install the relation or file with this flag, or not. - `included` This flag is only valid for relations. It specifies, that the related addon is included in this one. This also means, that if some addon requires the related addon, it can also be installed with this addon instead. - Relations with this flag must have an exact version specified, a version range, which includes multiple versions + Relations with this flag MUST have an exact version specified, a version range, which includes multiple versions is not allowed. If this flag is used together with `required` or `optional`, the files of the related addon will be installed like if the relation wouldn't have this flag, relations of the related addon will however be ignored since AddonScript assumes, that they are already covered by this addon. @@ -34,9 +34,9 @@ addon manifest, including for which side it is available and for which side it i that they can't be installed together in the same instance. For a file this flag specifies, that the file can't be installed on the side which has this flag set. - `launch` This flag is only valid for instance addons. For a relation this flag specifies, that the launch configuration - should be delegated to the related addon. The related addon must also be an instance addon on that side. For a file this - flag specifies, that the file should be the launch file of this addon. On the client side the launch file must be a + will be delegated to the related addon. The related addon MUST also be an instance addon on that side. For a file this + flag specifies, that the file will be the launch file of this addon. On the client side the launch file MUST be a [client JSON file](https://minecraft.fandom.com/wiki/Client.json) which contains the client launch configuration. - On the server side the launch file must be an executable jar file, which should be executed to start the server. + On the server side the launch file MUST be an executable jar file, which will be executed to start the server. This jar file will implicitly be installed by being moved to the root of the server directory. This flag always also implies any effect of `required`. \ No newline at end of file diff --git a/docs/concepts/install.md b/docs/concepts/install.md index 74606a6..1ae35d4 100644 --- a/docs/concepts/install.md +++ b/docs/concepts/install.md @@ -8,8 +8,7 @@ args: - `[location]` -`move` is simplest install action of all. It just moves the file to -the given location. +`move` moves the file to the given location. ### extract @@ -32,13 +31,13 @@ args: `inject` can be used with zip or jar files, to inject the contents of that file into the server launch jar on server side or into the client jar on client side. -In contrast to libraries, `inject` will not add that file to the classpath, but +In contrast to libraries, `inject` will not add just that file to the classpath, but will also overwrite classes, which are already contained in the game jar, if they are also in injected file. ## Locations -Locations are specified as a relative path from the Minecraft directory to which the file should be installed. +Locations are specified as a relative path from the Minecraft directory to which the file will be installed. For example `./mods` would point to the mods directory of the Minecraft instance. ## Directories diff --git a/docs/concepts/instance.md b/docs/concepts/instance.md index ad43134..4ca6da0 100644 --- a/docs/concepts/instance.md +++ b/docs/concepts/instance.md @@ -1,16 +1,16 @@ # Instance addons Instance addons represent instances of Minecraft itself, while non-instance addons -have to be installed into an existing instance of Minecraft. An instance addon requires +have to be installed into an existing instance of Minecraft. An instance addon MUST have a launch configuration for each side for which it is available. This means, that an instance -addon must have exactly one [file](../schema/file.md) or [relation](../schema/relation.md) -for each side, which has the `launch` [flag](flags.md) flag. A file can not have this flag -on both sides, since the file type is different for each side, while a relation may have +addon MUST have exactly one [file](../schema/file.md) or [relation](../schema/relation.md) +for each side, which has the `launch` [flag](flags.md) flag. A file MUST NOT have this flag +on both sides, since the file type is different for each side, while a relation MAY have it on both sides, as long as the related addon is itself an instance addon for both sides. ## Instance addons as relations If an instance addon is a relation of another instance addon, each side of that -relation requires to have at least one of the [flags](flags.md) `included`, `launch` -or `incompatible`. Non-instance addons may have instance addons as relations without +relation MUST have at least one of the [flags](flags.md) `included`, `launch` +or `incompatible`. Non-instance addons MAY have instance addons as relations without this restrictions. \ No newline at end of file diff --git a/docs/concepts/links.md b/docs/concepts/links.md index b521b75..96060b7 100644 --- a/docs/concepts/links.md +++ b/docs/concepts/links.md @@ -1,6 +1,6 @@ # Links -AddonScript uses links to point to specific files. AddonScript specifies three link types, which can be used +AddonScript uses links to point to specific files. AddonScript specifies two link types, which can be used to point to files. ## http(s) diff --git a/docs/concepts/namespaces.md b/docs/concepts/namespaces.md index 84590e5..471db7e 100644 --- a/docs/concepts/namespaces.md +++ b/docs/concepts/namespaces.md @@ -4,23 +4,23 @@ Namespaces are used in conjunction with addon IDs to uniquely identify an addon. ## Format -Namespaces may only contain lowercase alphanumeric characters, hyphens (should be avoided) and dots. -They should be in a reversed domain name format. A namespace should specify the distribution source +Namespaces MUST only contain lowercase alphanumeric characters, hyphens (SHOULD be avoided) and dots. +They SHOULD be in a reversed domain name format. A namespace SHOULD specify the distribution source (i.e. `com.example.repository`) or the author (i.e. `com.author.website`) of the addon and optionally also the addon type (i.e. `com.example.repository.mods`, `com.author.website.modpacks`). ## Canonical Namespaces -While an addon can have multiple namespaces, it must have exactly one canonical +While an addon MAY have multiple namespaces, it MUST have exactly one canonical namespace, which is defined in the [addon manifest](../schema/manifest.md#namespace). -An [API instance](../api/) must also return the canonical namespace of +An [API instance](../api/) MUST also return the canonical namespace of the addon on the [addon endpoint](../api/features/addons.md#get-addon) even if the addon was requested from another namespace. To check, if two addons -are the same addon, thier canonical namespace and their ID must be equal. +are the same addon, their canonical namespace and their ID MUST be equal. ## Default Namespaces Each [API instance](../api/) has a default namespace. Addons in the -repository of that API instance should have that namespace, as long as there +repository of that API instance SHOULD have that namespace, as long as there are no ID conflicts in the repository. The default namespace does not need to be the canonical namespace of these addons. \ No newline at end of file diff --git a/docs/concepts/versioning.md b/docs/concepts/versioning.md index db5d57a..c9157c9 100644 --- a/docs/concepts/versioning.md +++ b/docs/concepts/versioning.md @@ -1,7 +1,7 @@ # 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. +that AddonScript version numbers MUST only contain non-space ASCII characters. ## Maven Versioning Specification diff --git a/docs/packaging/zip.md b/docs/packaging/zip.md index ceb6033..279c291 100644 --- a/docs/packaging/zip.md +++ b/docs/packaging/zip.md @@ -1,7 +1,7 @@ # Zip Packaging With zip packaging, the AddonScript file and the associated files are contained in -a zip file. The AddonScript file has to be called `addon.json` and can either be placed +a zip file. The AddonScript file MUST be named `addon.json` and MUST either be placed at the root of the zip file or, if there is just one directory in the root of the zip file, in this directory. All files and directories inside the zip file can be accessed from AddonScript using the [file links](../concepts/links.md#file). The path from the file URL is relative to the location of diff --git a/docs/schema/api_addon.md b/docs/schema/api_addon.md index c76aeb5..5a62db3 100644 --- a/docs/schema/api_addon.md +++ b/docs/schema/api_addon.md @@ -20,7 +20,7 @@ This is the ID of the addon. -It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces. +It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD be written in the `kebab-case` format. ### namespace diff --git a/docs/schema/api_file.md b/docs/schema/api_file.md index 2c4407c..d4bdd20 100644 --- a/docs/schema/api_file.md +++ b/docs/schema/api_file.md @@ -16,8 +16,8 @@ ### link -This is an array of [links](../concepts/links.md), which are pointing to the actual file. This must be a http(s) link. -All of these links must have the same file type. +This is an array of [links](../concepts/links.md), which are pointing to the actual file. These MUST be a http(s) links. +All of these links MUST have the same file type. ## Optional properties @@ -31,4 +31,4 @@ Supported hash algorithms: ### meta -This is a [meta object](meta.md) containing metadata about the file. it may only contain [additional metadata](meta.md#additional). \ No newline at end of file +This is a [meta object](meta.md) containing metadata about the file. it SHOULD only contain [additional metadata](meta.md#additional). \ No newline at end of file diff --git a/docs/schema/file.md b/docs/schema/file.md index e2f554e..cf0b9f4 100644 --- a/docs/schema/file.md +++ b/docs/schema/file.md @@ -17,7 +17,7 @@ ### qualifier This is the qualifier of this file. -It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces. +It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD be written in the `kebab-case` format. The qualifier has to be unique to this addon version. The namespace, addon ID, version and qualifier can together be used to uniquely identify a file. @@ -26,8 +26,8 @@ can together be used to uniquely identify a file. This is an array of [links](../concepts/links.md), which are pointing to the actual file. All of these links must have the same file type. Since AddonScript treats directories and zip files equally, they can be mixed in the same link array. When downloading the file, -the first link in this array should be used with the other links as fallback, if the first doesn't work. -If none of the specified links works or the array is empty, the file link should be retrieved by it's identifier +the first link in this array SHOULD be used with the other links as fallback, if the first doesn't work. +If none of the specified links works or the array is empty, the file link SHOULD be retrieved by it's identifier from one of the [repositories](repository.md), but only, if a `sha1` hash is specified, so that it can be verified, that the downloaded file is correct. @@ -35,8 +35,8 @@ verified, that the downloaded file is correct. ### install -This is an array of [install objects](install.md). They describe how the file should be installed to the game. -The order in the array corresponds to the order in which the installation steps should be applied. +This is an array of [install objects](install.md). They describe how the file will be installed to the game. +The order in the array corresponds to the order in which the installation steps will be applied. ### flags diff --git a/docs/schema/install.md b/docs/schema/install.md index ef75d54..54fd1a0 100644 --- a/docs/schema/install.md +++ b/docs/schema/install.md @@ -11,7 +11,7 @@ ### action -This is the [install action](../concepts/install.md), which should be used at this installation step. +This is the [install action](../concepts/install.md), which will be used at this installation step. ## Optional properties diff --git a/docs/schema/manifest.md b/docs/schema/manifest.md index 5cb72c6..a42593b 100644 --- a/docs/schema/manifest.md +++ b/docs/schema/manifest.md @@ -25,7 +25,7 @@ This is an [AddonScript object](addonscript.md) containing information about the This is the ID of the addon. -It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces. +It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD be written in the `kebab-case` format. ### version @@ -45,7 +45,7 @@ This is an [flags object](flags.md) which contains [manifest flags](../concepts/ ### 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). +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 diff --git a/docs/schema/meta.md b/docs/schema/meta.md index 4dbfc2d..0c3bcf5 100644 --- a/docs/schema/meta.md +++ b/docs/schema/meta.md @@ -41,17 +41,17 @@ This object can contain any arbitrary data, ### name -The full, human-readable name of the addon. This is what a program such as a launcher should +The full, human-readable name of the addon. This is what a program such as a launcher SHOULD display to the user. ### icon -A [link](../concepts/links.md) to the icon of the addon. This path should point to an image file of small resolution -which is ideally square. It can be dispayed to users in programs. +A [link](../concepts/links.md) to the icon of the addon. This path SHOULD point to an image file of small resolution +which is ideally square. It MAY be dispayed to users in programs. ### description -A [link](../concepts/links.md) to a description file for the addon. The file should be in CommonMark markdown. +A [link](../concepts/links.md) to a description file for the addon. The file SHOULD be in CommonMark markdown. ### summary @@ -75,7 +75,8 @@ The type of the addon, for example `mod`, `modpack` or `resourcepack`. ### contributors -An array of people who have contributed to the addon. +An array of people who have contributed to the addon. Each contributor is represented by an object, which +MUST have a `name` and a `email` property. # Version Meta Object diff --git a/docs/schema/relation.md b/docs/schema/relation.md index 2e02402..d6c034a 100644 --- a/docs/schema/relation.md +++ b/docs/schema/relation.md @@ -26,7 +26,7 @@ This is the [namespace](../concepts/namespaces.md) of the related addon. This pr ### 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 has to be set. +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 @@ -35,9 +35,9 @@ It will only allow versions of the related addon, which have a valid semver vers ### repositories -This is an array of [repository](repository.md) IDs. These are the repositories, from which AddonScript should try to get this relation from, +This is an array of [repository](repository.md) IDs. These are the repositories, from which AddonScript will try to get this relation from, in the order as they are specified 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. +the namespace from all [defined repositories](manifest.md#repositories). ### flags diff --git a/docs/schema/repository.md b/docs/schema/repository.md index ed17840..851486c 100644 --- a/docs/schema/repository.md +++ b/docs/schema/repository.md @@ -11,7 +11,7 @@ ### id -This is the ID of the repository. It has to be unique to the AddonScript file. +This is the ID of the repository. It MUST be unique in the [manifest](manifest.md). ### url