Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add a note on policy on relationship metadata #3930

Merged
merged 3 commits into from
Nov 22, 2023
Merged

Add a note on policy on relationship metadata #3930

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
62a83e2
Add a note on policy on relationship metadata
JonnyOThan Nov 22, 2023
5e13f45
Linting clean-up of old content
HebaruSan Nov 22, 2023
c3ed6aa
Move "A note ..." section into main Relationships section
HebaruSan Nov 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
47 changes: 29 additions & 18 deletions Spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -425,7 +424,7 @@ Example tags:

Currently recommended tags are listed here:

https://github.com/KSP-CKAN/CKAN/wiki/Suggested-Tags
<https://github.com/KSP-CKAN/CKAN/wiki/Suggested-Tags>

##### localizations

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand Down