contentdb/app/flatpages/help/package_config.md

143 lines
4.3 KiB
Markdown
Raw Normal View History

2020-06-03 19:22:23 +02:00
title: Package Configuration and Releases Guide
## Introduction
2020-09-17 00:32:24 +02:00
ContentDB will read configuration files in your package when doing several
tasks, including package and release creation. This page details how you can use
this to your advantage.
2020-06-03 19:22:23 +02:00
## .conf files
2020-09-17 00:32:24 +02:00
### What is a content .conf file?
2020-06-03 19:22:23 +02:00
Every type of content can have a `.conf` file that contains the metadata.
The filename of the `.conf` file depends on the content type:
* `mod.conf` for mods.
* `modpack.conf` for mod packs.
* `game.conf` for games.
* `texture_pack.conf` for texture packs.
The `.conf` uses a key-value format, separated using equals.
Here's a simple example of `mod.conf`, `modpack.conf`, or `texture_pack.conf`:
2020-06-03 19:22:23 +02:00
name = mymod
2022-08-19 01:06:54 +02:00
title = My Mod
2020-06-03 19:22:23 +02:00
description = A short description to show in the client.
Here's a simple example of `game.conf`:
title = My Game
description = A short description to show in the client.
Note that you should not specify `name` in game.conf.
2020-09-17 00:32:24 +02:00
### Understood values
2020-06-03 19:22:23 +02:00
ContentDB understands the following information:
2022-08-19 01:06:54 +02:00
* `title` - A human-readable title.
2020-06-03 19:22:23 +02:00
* `description` - A short description to show in the client.
* `depends` - Comma-separated hard dependencies.
2020-06-03 19:28:08 +02:00
* `optional_depends` - Comma-separated soft dependencies.
2020-09-17 00:32:24 +02:00
* `min_minetest_version` - The minimum Minetest version this runs on, see [Min and Max Minetest Versions](#min_max_versions).
* `max_minetest_version` - The maximum Minetest version this runs on, see [Min and Max Minetest Versions](#min_max_versions).
2020-06-03 19:22:23 +02:00
and for mods only:
* `name` - the mod technical name.
* `supported_games` - List of supported game technical names.
* `unsupported_games` - List of not supported game technical names. Useful to override game support detection.
2020-06-03 19:22:23 +02:00
2021-02-03 00:58:59 +01:00
## .cdb.json
You can include a `.cdb.json` file in the root of your content directory (ie: next to a .conf)
to update the package meta.
It should be a JSON dictionary with one or more of the following optional keys:
2021-02-03 00:58:59 +01:00
* `type`: One of `GAME`, `MOD`, `TXP`.
* `title`: Human-readable title.
* `name`: Technical name (needs permission if already approved).
* `short_description`
2021-12-20 22:07:12 +01:00
* `dev_state`: One of `WIP`, `BETA`, `ACTIVELY_DEVELOPED`, `MAINTENANCE_ONLY`, `AS_IS`, `DEPRECATED`,
`LOOKING_FOR_MAINTAINER`.
2021-02-03 00:58:59 +01:00
* `tags`: List of tag names, see [/api/tags/](/api/tags/).
* `content_warnings`: List of content warning names, see [/api/content_warnings/](/api/content_warnings/).
2021-02-03 00:58:59 +01:00
* `license`: A license name, see [/api/licenses/](/api/licenses/).
* `media_license`: A license name.
2021-02-03 01:14:14 +01:00
* `long_description`: Long markdown description.
2023-11-19 14:39:38 +01:00
* `repo`: Source repository (eg: Git).
2021-02-03 00:58:59 +01:00
* `website`: Website URL.
* `issue_tracker`: Issue tracker URL.
* `forums`: forum topic ID.
* `video_url`: URL to a video.
2023-03-05 19:13:07 +01:00
* `donate_url`: URL to a donation page.
2021-02-03 00:58:59 +01:00
Use `null` or `[]` to unset fields where relevant.
2021-02-03 00:58:59 +01:00
Example:
```json
{
"title": "Foo bar",
"tags": ["pvp", "survival"],
"license": "MIT",
"website": null
2021-02-03 00:58:59 +01:00
}
```
2020-06-03 19:22:23 +02:00
## Controlling Release Creation
2020-09-17 00:32:24 +02:00
### Git-based Releases and Submodules
2020-06-03 19:28:08 +02:00
2020-09-17 00:32:24 +02:00
ContentDB can create releases from a Git repository.
2020-06-03 19:28:08 +02:00
It will include submodules in the resulting archive.
2020-09-17 00:32:24 +02:00
Simply set VCS Repository in the package's meta to a Git repository, and then
choose Git as the method when creating a release.
2020-06-03 19:28:08 +02:00
2020-06-03 19:22:23 +02:00
### Automatic Release Creation
See [Git Update Detection](/help/update_config/).
You can also use [GitLab/GitHub webhooks](/help/release_webhooks/) or the [API](/help/api/)
to create releases.
2020-06-03 19:22:23 +02:00
### Min and Max Minetest Versions
2020-09-17 00:32:24 +02:00
<a name="min_max_versions" />
2020-06-03 19:22:23 +02:00
When creating a release, the `.conf` file will be read to determine what Minetest
versions the release supports. If the `.conf` doesn't specify, then it is assumed
2020-09-17 00:32:24 +02:00
that it supports all versions.
2020-06-03 19:22:23 +02:00
This happens when you create a release via the ContentDB web interface, the
[API](/help/api/), or using a [GitLab/GitHub webhook](/help/release_webhooks/).
2020-09-17 00:32:24 +02:00
Here's an example config:
name = mymod
min_minetest_version = 5.0
max_minetest_version = 5.3
Leaving out min or max to have them set as "None".
2020-06-03 19:22:23 +02:00
### Excluding files
2020-09-17 00:32:24 +02:00
When using Git to create releases,
2020-06-03 19:28:08 +02:00
you can exclude files from a release by using [gitattributes](https://git-scm.com/docs/gitattributes):
2020-06-03 19:22:23 +02:00
.* export-ignore
sources export-ignore
*.zip export-ignore
This will prevent any files from being included if they:
* Beginning with `.`
* or are named `sources` or are inside any directory named `sources`.
* or have an extension of "zip".