Revamped: Central Server Docs

Reloaded-Project · May 31, 2024 · 946705a · 946705a
1 parent f56178a
commit 946705a
Show file tree

Hide file tree

Showing 7 changed files with 446 additions and 145 deletions.
diff --git a/docs/Common/Localisation/Adding-Localisations.md b/docs/Common/Localisation/Adding-Localisations.md
@@ -12,7 +12,7 @@ Such as a mod, utility, etc.
 reloaded3.utility.examplemod.s56
 ├── languages
 │   ├── en-GB.toml
-│   └── uwu.toml
+│   └── uwu-en.toml
 ├── config.toml
 └── package.toml
 ```
@@ -30,15 +30,17 @@ For example, a localisable config and `DLL` code loaded at runtime.
 
 ```
 reloaded3.utility.examplemod.s56
+├── config
+│   └── config.toml
+├── modfiles
+│   └── mod.dll
 ├── languages
 │   ├── config
 │   │   ├── en-GB.toml
-│   │   └── uwu.toml
+│   │   └── uwu-en.toml
 │   └── dll
 │       ├── en-GB.toml
-│       └── uwu.toml
-├── config.toml
-├── mod.dll
+│       └── uwu-en.toml
 └── package.toml
 ```
 
@@ -145,6 +147,59 @@ reloaded3.utility.examplemod.s56.de
 
 This would add a German translation to both the config and the DLL.
 
+## Updating Translations
+
+!!! warning "Keys in translations must NEVER be changed."
+
+    This is to ensure backwards compatibility in [Sideloaded Translations](#sideloading-translations).
+
+Suppose you have a translation file with the following content:
+
+```toml
+## Update 1.0.0 | 2024 April 1st
+## Initial Release
+[[ADD_AN_APPLICATION]]
+Add an Application
+```
+
+At some point you decide you're no longer supporting 'Applications' but instead 'Games'.
+
+!!! success "The correct approach here is to add a new key."
+
+```toml
+## Update 1.0.0 | 2024 April 1st
+## Initial Release
+
+# DEPRECATED in 2.0.0 by `ADD_A_GAME`
+# [[ADD_AN_APPLICATION]]
+# Add an Application
+
+## Update 2.0.0 | 2024 May 1st
+## We now only support games.
+[[ADD_A_GAME]]
+Add a Game
+```
+
+In this way, people who use a newer translation, can still use it with older versions of the package.
+
+!!! note "Original language (e.g. English) can comment out unused strings."
+
+    Non-original language ***must keep all strings uncommented***, in case a newer translation is used
+    with an older version of original package.
+
+## Special Keys
+
+!!! info "Some applications may reserve keys for special purposes."
+
+!!! example "Reloaded3 uses the `NATIVE_NAME` key to store the display name of the language."
+
+    ```toml
+    [[DISPLAY_NAME]]
+    UwU (English)
+    ```
+
+This is application specific, and not standardised.
+
 [iso-lang-code]: https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
 [iso3166-alpha2]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
 [package-type]: ../../Server/Packaging/Package-Metadata.md#packagetype
diff --git a/docs/Server/Packaging/About.md b/docs/Server/Packaging/About.md
@@ -9,36 +9,56 @@ Each mod package contains the following approximate structure.
 
 ```
 reloaded3.utility.examplemod.s56
+├── config
+│   ├── config-image-1.jxl
+│   └── config.toml
+├── languages
+│   ├── config
+│   │   ├── en-GB.toml
+│   │   └── uwu-en.toml
+│   └── dll
+│       ├── en-GB.toml
+│       └── uwu-en.toml
+├── modfiles
+│   ├── redirector
+│   │   └── skill-game-asset.bin
+│   └── mod.dll
 ├── package
-│   ├── changelog
-│   │   ├── 1.0.0.md
-│   │   ├── 1.1.0.md
-│   │   ├── 1.2.0.md
-│   │   ├── 1.2.1.md
-│   │   └── 2.0.0.md
 │   ├── docs
+│   │   ├── changelog
+│   │   │   ├── 1.0.0.md
+│   │   │   ├── 1.1.0.md
+│   │   │   ├── 1.2.0.md
+│   │   │   ├── 1.2.1.md
+│   │   │   └── 2.0.0.md
 │   │   └── index.html
 │   ├── images
 │   │   ├── skill-1.jxl
 │   │   ├── skill-2.jxl
 │   │   └── skill-3.jxl
 │   ├── description.md
-│   ├── files.meta
 │   └── license.md
-├── redirector
-│   └── skill-game-asset.bin
-├── config.toml
 └── package.toml
 ```
 
 ### Changelog
 
-!!! info "Located in `package/changelog`."
+!!! info "Located in `package/docs/changelog`."
 
 !!! info "This contains the changelog for each version of the mod up until the current version."
 
 Each version is contained in its own `Markdown` file, e.g. `1.0.0.md`.
 
+!!! note "Having `Docs` is not required to have `Changelogs`"
+
+    The `Changelog` exists in the `docs` part of the folder because they
+    commonly share images. It also allows you to have the Changelogs
+    as separate documentation pages.
+
+    Some documentation building tools may require that all images are
+    within a certain subfolder, thus to allow image reuse, we put the
+    changelog pages within the docs folder.
+
 ### Config
 
 !!! info "Located at `package/config.toml`."
@@ -79,6 +99,8 @@ Currently accepted formats include:
 
 The entry point for the documentation is specified in the [DocsFile][docs-file] field in the `package.toml`.
 
+!!! tip "We recommand using `MkDocs Material` in CI for the documentation."
+
 ### Images
 
 !!! info "Located in `package/images`."

diff --git a/docs/Server/Packaging/Configurations/Mod-Metadata.md b/docs/Server/Packaging/Configurations/Mod-Metadata.md
@@ -24,18 +24,24 @@ Mod Metadata extends from standard ([package.toml][package-toml]).
 
 !!! info "Should be a multiple of `256x256`. Recommended `512x512`."
 
+Name of file in [images][package-images] folder.
+
 ### Icon (Banner)
 
 !!! info "Should be a multiple of `920x430`."
 
     Same as Steam (Horizontal) banners.
 
+Name of file in [images][package-images] folder.
+
 ### Icon (Poster)
 
 !!! info "Should be a multiple of `600x900`."
 
     Same as Steam (Vertical) covers/banners.
 
+Name of file in [images][package-images] folder.
+
 ## Gallery
 
 !!! info "Gallery images are stored in [images][package-images] folder."
@@ -57,6 +63,8 @@ Mod Metadata extends from standard ([package.toml][package-toml]).
 
 !!! info "This section specifies info for the individual [backends.][backend]"
 
+!!! info "These specify file paths relative to `modfiles` folder."
+
 Find more info on the pages for the [individual backends][backend], but we'll provide some examples.
 
 [Native Mod][native-backend]:

diff --git a/docs/Server/Packaging/Package-Metadata.md b/docs/Server/Packaging/Package-Metadata.md
@@ -13,6 +13,7 @@ Inside each package folder is a file named `package.toml`; which stores the meta
 | PackageType         | [PackageType](#packagetype)                | Type of the package. See [PackageType](#packagetype) for possible values. |
 | string              | [DocsFile](#docsfile)                      | [Optional] Entry point for this package documentation.                    |
 | SemVer              | [Version](#version)                        | Semantic versioning version of the package.                               |
+| string              | LicenseId                                  | [SPDX License Identifier][spdx-license]                                   |
 | string[]            | [Tags](#tags)                              | Used to make searching easier within mod managers.                        |
 | Credit[]            | [Credits](#credits)                        | [Optional] Stores information about who contributed what to the project.  |
 | string?             | SourceUrl                                  | [Optional] Link to source code (if applicable).                           |
@@ -28,6 +29,7 @@ Inside each package folder is a file named `package.toml`; which stores the meta
 Some items are stored as separate files:
 
 - [license][license]: License file, located in `package/license.md`.
+    - This is used if `LicenseId` is not specified.
 - [changelog][changelog]: Changelog file(s), located in `package/changelog/*.md`.
 - [description][description]: Description file, located in `package/description.md`.
 - [config][config]: Configuration schema for the package, located in `package/config.toml`.
@@ -433,4 +435,5 @@ If the `IgnoredDiagnostics` field is not specified or is an empty array, no diag
 [overriding-translations]: ../../Common/Localisation/Adding-Localisations.md#sideloading-translations
 [ready-to-run]: ../../Loader/Backends/CoreCLR.md#ready-to-run
 [reloaded2-backend]: ../../Loader/Backends/CoreCLR.md#reloaded-ii
-[semantic-versioning]: https://semver.org
+[semantic-versioning]: https://semver.org
+[spdx-license]: https://spdx.org/licenses/
diff --git a/docs/Server/Storage/Loadouts/About.md b/docs/Server/Storage/Loadouts/About.md
@@ -479,7 +479,7 @@ First we attempt to obtain full package metadata from [Central Server][central-s
 
 !!! failure "But what if [Central Server][central-server] is down?"
 
-We will query the [GitHub Fallback Package Dump][central-server-github].
+We will query the [Static CDN API][static-cdn-api].
 That contains a dump of the latest package update info.
 
 ### stores.bin
@@ -645,6 +645,5 @@ The lengths of the parameters are specified in the [UpdateCommandline event][upd
 [gog]: ./Stores/GOG.md
 [ms-store-pfm]: ../../../Loader/Copy-Protection/Windows-MSStore.md
 [gog-buildid]: ./Stores/GOG.md#retrieving-available-game-versions
-[package-metadata-server]: ../../../Services/Central-Server.md#package-metadata
 [central-server]: ../../../Services/Central-Server.md
-[central-server-github]: ../../../Services/Central-Server.md#redundancy-with-github
+[static-cdn-api]: ../../../Services/Central-Server.md#static-cdn-api