diff --git a/CHANGELOG.md b/CHANGELOG.md index bdf7b3b87a..2fd036b61e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -43,6 +43,7 @@ All notable changes to this project will be documented in this file. - [GUI] Add test to check GUI thread safety (#3914 by: HebaruSan; reviewed: techman83) - [Multiple] VSCode clean-up and other minor fixes (#3920 by: HebaruSan) - [Build] Modernize build system and .NET platform targets (#3929 by: HebaruSan; reviewed: techman83) +- [Spec] Add a note on policy on relationship metadata (#3930 by: JonnyOThan; reviewed: HebaruSan) ## v1.33.2 (Laplace) diff --git a/Spec.md b/Spec.md index a821ee6e3d..08eefb536d 100644 --- a/Spec.md +++ b/Spec.md @@ -58,7 +58,6 @@ files are simply JSON files using UTF-8 as character-encoding. Except where stated otherwise all strings *should* be printable unicode only. - CKAN files *should* have a naming scheme of their mod's identifier, followed by a dash, followed by the version number, followed by the extension `.ckan`. For example: `RealSolarSystem-7.3.ckan`. @@ -179,12 +178,12 @@ The license (**v1.0**), or list of licenses (**v1.8**), under which the mod is r The same rules as per the [Debian license specification](https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/#license-specification) apply, with the following modifications: -* The `MIT` license is always taken to mean the [Expat license](https://www.debian.org/legal/licenses/mit). -* The creative commons licenses are permitted without a version number, indicating the +- The `MIT` license is always taken to mean the [Expat license](https://www.debian.org/legal/licenses/mit). +- The creative commons licenses are permitted without a version number, indicating the author did not specify which version applies. -* Stripping of trailing zeros is not recognised. -* (**v1.2**) `WTFPL` is recognised as a valid license. -* (**v1.18**) `Unlicense` is recognised as a valid license. +- Stripping of trailing zeros is not recognised. +- (**v1.2**) `WTFPL` is recognised as a valid license. +- (**v1.18**) `Unlicense` is recognised as a valid license. The following license strings are also valid and indicate other licensing not described above: @@ -296,13 +295,13 @@ three source directives: In addition a destination directive *must* be provided: - `install_to`: The target location where the matched file or directory should be installed. - - Valid values for this entry for KSP1 mods are `GameData`, `Missions`(**v1.25**), `Ships`, `Ships/SPH`(**v1.12**), `Ships/VAB`(**v1.12**), `Ships/@thumbs/VAB`(**v1.16**), `Ships/@thumbs/SPH`(**v1.16**), `Ships/Script`(**v1.29**), `Tutorial`, `Scenarios` (**v1.14**), + - Valid values for this entry for KSP1 mods are `GameData`, `Missions`(**v1.25**), `Ships`, `Ships/SPH`(**v1.12**), `Ships/VAB`(**v1.12**), `Ships/@thumbs/VAB`(**v1.16**), `Ships/@thumbs/SPH`(**v1.16**), `Ships/Script`(**v1.29**), `Tutorial`, `Scenarios` (**v1.14**), and `GameRoot` (which should be used sparingly, if at all). - - Valid values for this entry for KSP2 mods are `GameRoot`, `BepInEx/plugins` (**v1.32**), and `GameData/Mods` (**v1.33**) - - A path to a given subfolder location can be specified *only* under `GameData` (**v1.2**); + - Valid values for this entry for KSP2 mods are `GameRoot`, `BepInEx/plugins` (**v1.32**), and `GameData/Mods` (**v1.33**) + - A path to a given subfolder location can be specified *only* under `GameData` (**v1.2**); for example: `GameData/MyMod/Plugins`. The client *must* check this path and abort the install if any attempts to traverse up directories are found (eg: `GameData/../Example`). - - Subfolder paths under a matched directory will be preserved, but directories will *only* + - Subfolder paths under a matched directory will be preserved, but directories will *only* be created when installing to `GameData`, `Tutorial`, or `Scenarios`. In addition, any number of optional directives *may* be provided: @@ -425,7 +424,7 @@ Example tags: Currently recommended tags are listed here: -https://github.com/KSP-CKAN/CKAN/wiki/Suggested-Tags + ##### localizations @@ -490,7 +489,7 @@ of the mod was released. The format is ISO 8601. "release_date": "2019-11-30T14:54:45.995Z", ``` -### Relationships +#### Relationships Relationships are optional fields which describe this mod's relationship to other mods. They can be used to ensure that a mod is installed with @@ -576,6 +575,17 @@ depends: suppress_recommendations: true ``` +In the interest of the end-user experience, the relationship metadata +*should* only be used when a game-related relationship exists between +the mods. They do not have to directly interact, but the rationale should be +apparent. It *should not* be used purely for promotional purposes. This is +consistent with [the Debian spec], which states: + +> tells the ... user that the listed packages are related to this one and can +perhaps enhance its usefulness + +[the Debian spec]: https://www.debian.org/doc/debian-policy/ch-relationships.html + ##### depends A list of mods which are *required* for the current mod to operate. @@ -621,7 +631,7 @@ replaced_by differs from other relationships in two ways: - It is *not* an array. Only a single mod can be defined as the replacement. - Only "version" and "min_version" are permitted as options. -#### resources +#### Resources The `resources` field describes additional information that a user or program may wish to know about the mod, but which are not required @@ -955,6 +965,7 @@ authoritative metadata. A metanetkan may be in either JSON or YAML format. The following conditions apply: + - A metanekan may not reference another metanetkan, otherwise an error is produced. - Any fields specified in the metanetkan will override any fields in the target netkan file. @@ -981,13 +992,13 @@ If present, a `$vref` symbol of `#/ckan/ksp-avc` states that version information should be retrieved from an embedded KSP-AVC `.version` file in the file downloaded by the `download` field. The following conditions apply: -* Only `.version` files that would be *installed* for this mod are considered. (In theory. Transformer ordering may cause files outside the installed folders being considered) -* It is an error if more than one `.version` file would be considered. -* It is an error if the `.version` file does not validate according to +- Only `.version` files that would be *installed* for this mod are considered. (In theory. Transformer ordering may cause files outside the installed folders being considered) +- It is an error if more than one `.version` file would be considered. +- It is an error if the `.version` file does not validate according to [the KSP-AVC spec]. -* The `KSP_VERSION` field for the `.version` file will be ignored if the +- The `KSP_VERSION` field for the `.version` file will be ignored if the `KSP_VERSION_MIN` and `KSP_VERSION_MAX` fields are set. -* Netkan will first attempt to use anything after `ksp-avc` as a literal +- Netkan will first attempt to use anything after `ksp-avc` as a literal path within the zip file, and if that fails, will use the string as a regexp to search for a matching file to use.