From 749e7c6cd04216abf727985805064510e85999f3 Mon Sep 17 00:00:00 2001
From: rubenwardy <rw@rubenwardy.com>
Date: Wed, 3 Jun 2020 18:22:23 +0100
Subject: [PATCH] Add Package Config help page

---
 app/blueprints/api/endpoints.py      |  3 --
 app/flatpages/help.md                | 12 ++---
 app/flatpages/help/api.md            |  7 ++-
 app/flatpages/help/package_config.md | 67 ++++++++++++++++++++++++++++
 4 files changed, 76 insertions(+), 13 deletions(-)
 create mode 100644 app/flatpages/help/package_config.md

diff --git a/app/blueprints/api/endpoints.py b/app/blueprints/api/endpoints.py
index 29a9ec2..fc3ba8f 100644
--- a/app/blueprints/api/endpoints.py
+++ b/app/blueprints/api/endpoints.py
@@ -28,9 +28,6 @@ from app.querybuilder import QueryBuilder
 
 @bp.route("/api/packages/")
 def packages():
-	import sys
-	print("\n\n############", file=sys.stderr)
-
 	qb    = QueryBuilder(request.args)
 	query = qb.buildPackageQuery()
 	ver   = qb.getMinetestVersion()
diff --git a/app/flatpages/help.md b/app/flatpages/help.md
index 784adf7..456f2bb 100644
--- a/app/flatpages/help.md
+++ b/app/flatpages/help.md
@@ -1,8 +1,6 @@
 title: Help
 
-## Content
-
-Policies and user help.
+## For Everyone
 
 * [Content Ratings and Flags](content_flags)
 * [Non-free Licenses](non_free)
@@ -11,10 +9,12 @@ Policies and user help.
 * [Reporting Content](reporting)
 * [Top Packages Algorithm](top_packages)
 
-## Developers
+## For Content Creators / Modders
 
-Various APIs.
+* [Creating Releases using Webhooks](release_webhooks)
+* [Package Configuration and Releases Guide](package_config)
+
+## For Developers
 
 * [API](api)
 * [Metrics](metrics)
-* [Creating Releases using Webhooks](release_webhooks)
diff --git a/app/flatpages/help/api.md b/app/flatpages/help/api.md
index c8f0f59..b032b5d 100644
--- a/app/flatpages/help/api.md
+++ b/app/flatpages/help/api.md
@@ -9,7 +9,7 @@ Authentication is done using Bearer tokens:
 
 You can use the `/api/whoami` to check authentication.
 
-Tokens can be attained by visiting "API Tokens" on your profile page.
+Tokens can be attained by visiting [Profile > "API Tokens"](/user/tokens/).
 
 ## Endpoints
 
@@ -33,16 +33,15 @@ Tokens can be attained by visiting "API Tokens" on your profile page.
 	* Requires authentication.
 	* `title`: human-readable name of the release.
 	* `method`: Release-creation method, only `git` is supported.
-	* `min_protocol`: (Optional) minimum Minetest protocol version. See [Minetest](#minetest).
-	* `min_protocol`: (Optional) maximum Minetest protocol version. See [Minetest](#minetest).
 	* If `git` release-creation method:
 		* `ref` - git reference, eg: `master`.
+	* You can set min and max Minetest Versions [using the content's .conf file](/help/package_config/).
 
 
 ### Topics
 
 * GET `/api/topics/` - Supports [Package Queries](#package-queries), and the following two options:
-    * `show_added` - Show topics which exist as packages, default true.
+	* `show_added` - Show topics which exist as packages, default true.
 	* `show_discarded` - Show topics which have been marked as outdated, default false.
 
 ### Minetest
diff --git a/app/flatpages/help/package_config.md b/app/flatpages/help/package_config.md
new file mode 100644
index 0000000..61bc5b2
--- /dev/null
+++ b/app/flatpages/help/package_config.md
@@ -0,0 +1,67 @@
+title: Package Configuration and Releases Guide
+
+## Introduction
+
+ContentDB will read configuration files in your package when doing a number of
+tasks, including package and release creation.
+This page details the ways in which you can use this to your advantage.
+
+## .conf files
+
+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:
+
+	name = mymod
+	description = A short description to show in the client.
+
+ContentDB understands the following information:
+
+* `description` - A short description to show in the client.
+* `depends` - Comma-separated hard dependencies.
+* `optional_depends` - Comma-separated hard dependencies.
+* `min_minetest_version` - The minimum Minetest version this runs on.
+* `min_minetest_version` - The minimum Minetest version this runs on.
+
+and for mods only:
+
+* `name` - the mod technical name.
+
+## Controlling Release Creation
+
+### Automatic Release Creation
+
+The preferred way is to use [webhooks from GitLab or GitHub](/help/release_webhooks/).
+You can also use the [API](/help/api/) to create releases.
+
+### Min and Max Minetest Versions
+
+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
+that is supports all versions.
+
+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/).
+
+### Excluding files
+
+You can exclude files from a release by using [gitattributes](https://git-scm.com/docs/gitattributes):
+
+
+	.*		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".