Improve documentation

This commit is contained in:
rubenwardy 2020-09-16 23:32:24 +01:00
parent a1e0e37223
commit d76f10c312
10 changed files with 271 additions and 242 deletions

View File

@ -15,7 +15,7 @@
# along with this program. If not, see <https://www.gnu.org/licenses/>.
from flask import Blueprint, make_response
from app.models import Package, PackageRelease, db, User, UserRank
from app.models import Package, PackageRelease, db, User, UserRank, PackageState
from sqlalchemy.sql.expression import func
bp = Blueprint("metrics", __name__)

View File

@ -1,20 +1,22 @@
title: Help
## For Everyone
## General Help
* [Content Ratings and Flags](content_flags)
* [Non-free Licenses](non_free)
* [Package Tags](package_tags)
* [Why WTFPL is a terrible license](wtfpl)
* [Ranks and Permissions](ranks_permissions)
* [Reporting Content](reporting)
* [Top Packages Algorithm](top_packages)
## For Content Creators / Modders
## Help for Package Authors
* [Package Inclusion Policy and Guidance](/policy_and_guidance/)
* [Package Tags](package_tags)
* [Creating Releases using Webhooks](release_webhooks)
* [Package Configuration and Releases Guide](package_config)
## For Developers
## APIs
* [API](api)
* [Metrics](metrics)
* [Prometheus Metrics](metrics)

View File

@ -6,13 +6,22 @@ your client to use new flags.
## Flags
Minetest allows you to specify a comma-separated list of flags to hide in the
client:
```
contentdb_flag_blacklist = nonfree, bad_language, drugs
```
A flag can be:
* `nonfree` - can be used to hide packages which do not qualify as
'free software', as defined by the Free Software Foundation.
* A content warning, given below.
* `android_default` - meta-flag that filters out any content with a content warning.
* `desktop_default` - meta-flag that doesn't filter anything out for now.
## Warnings
## Content Warnings
Packages with mature content will be tagged with a content warning based
on the content type.

View File

@ -10,13 +10,13 @@ and they will be subject to limited promotion.
## How does ContentDB deal with Non-Free Licenses?
ContentDB does not allow certain non-free licenses, and will limit the promotion
of packages with non-free licenses.
**ContentDB does not allow certain non-free licenses, and will limit the promotion
of packages with non-free licenses.**
Minetest is free and open source software, and is only as big as it is now
because of this. It's pretty amazing you can take nearly any published mod and modify it
to how you like - add some features, maybe fix some bugs - and then share those
modifications without worry of legal issues. The project, itself, relies on open
modifications without the worry of legal issues. The project, itself, relies on open
source contributions to survive - if it were non-free, then it would have died
when celeron55 lost interest.
@ -43,7 +43,7 @@ Here's a quick summary related to Minetest content:
you do want to allow derivative works or combinations.
This means that it can cause problems when another modder wishes to include your
work in a modpack or game.
2. They may rule out other basic and beneficial uses which you want to allow.
2. They may rule out other basic and beneficial uses that you want to allow.
For example, CC -NC will forbid showing your content in a monetised YouTube
video.
3. They are unlikely to increase the potential profit from your work, and a

View File

@ -2,12 +2,14 @@ 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.
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.
## .conf files
### What is a content .conf file?
Every type of content can have a `.conf` file that contains the metadata.
The filename of the `.conf` file depends on the content type:
@ -22,13 +24,15 @@ The `.conf` uses a key-value format, separated using equals. Here's a simple exa
name = mymod
description = A short description to show in the client.
### Understood values
ContentDB understands the following information:
* `description` - A short description to show in the client.
* `depends` - Comma-separated hard dependencies.
* `optional_depends` - Comma-separated soft dependencies.
* `min_minetest_version` - The minimum Minetest version this runs on.
* `max_minetest_version` - The maximum Minetest version this runs on.
* `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).
and for mods only:
@ -36,10 +40,12 @@ and for mods only:
## Controlling Release Creation
### Git Releases and Submodules
### Git-based Releases and Submodules
ContentDB can automatically create releases from a git repository.
ContentDB can create releases from a Git repository.
It will include submodules in the resulting archive.
Simply set VCS Repository in the package's meta to a Git repository, and then
choose Git as the method when creating a release.
### Automatic Release Creation
@ -48,16 +54,26 @@ You can also use the [API](/help/api/) to create releases.
### Min and Max Minetest Versions
<a name="min_max_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.
that it 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/).
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".
### Excluding files
When using git to create releases,
When using Git to create releases,
you can exclude files from a release by using [gitattributes](https://git-scm.com/docs/gitattributes):

View File

@ -3,24 +3,24 @@ title: Ranks and Permissions
## Overview
* **New Members** - mostly untrusted, cannot change package meta data or publish releases without approval.
* **Members** - Trusted to change the meta data of their own packages', but cannot publish releases.
* **Trusted Members** - Same as above, but can approve their own releases and packages.
* **Editors** - Trusted to change the meta data of any package, and also make and publish releases.
* **Members** - Trusted to change the meta data of their own packages', but cannot approve their own packages.
* **Trusted Members** - Same as above, but can approve their own releases.
* **Editors** - Trusted to edit any package or release, and also responsible for approving new packages.
* **Moderators** - Same as above, but can manage users.
* **Admins** - Full access.
## Breakdown
<table class="table">
<table class="table table-striped ranks-table">
<thead>
<tr>
<th>Rank</th>
<th colspan=2>New Member</th>
<th colspan=2>Member</th>
<th colspan=2>Trusted Member</th>
<th colspan=2>Editor</th>
<th colspan=2>Moderator</th>
<th colspan=2>Admin</th>
<th colspan=2 class="NEW_MEMBER">New Member</th>
<th colspan=2 class="MEMBER">Member</th>
<th colspan=2 class="TRUSTED_MEMBER">Trusted</th>
<th colspan=2 class="EDITOR">Editor</th>
<th colspan=2 class="MODERATOR">Moderator</th>
<th colspan=2 class="ADMIN">Admin</th>
</tr>
<tr>
<th>Owner of thing</th>
@ -41,228 +41,228 @@ title: Ranks and Permissions
<tbody>
<tr>
<td>Create Package</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<th></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<td></td>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>Approve Package</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<th></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<td></td>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>Delete Package</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<th></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<td></td>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>Edit Package</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<th></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<td></td>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>Edit Maintainers</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<th></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<td></td>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>Add/Delete Screenshot</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<th></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<td></td>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>Approve Screenshot</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<th></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<td></td>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>Make Release</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<th></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<td></td>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>Approve Release</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<th></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<td></td>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>Change Release URL</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<th></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<td></td>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>See Private Thread</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<th></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<td></td>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>Edit Comments</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<th></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<td></td>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>Set Email</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<th><sup>2</sup></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>Create Token</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<th></th> <!-- moderator -->
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<td></td> <!-- moderator -->
<th><sup>2</sup></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- admin -->
<td></td>
</tr>
<tr>
<td>Set Rank</td>
<th></th> <!-- new -->
<th></th>
<th></th> <!-- member -->
<th></th>
<th></th> <!-- trusted member -->
<th></th>
<th></th> <!-- editor -->
<th></th>
<td></td> <!-- new -->
<td></td>
<td></td> <!-- member -->
<td></td>
<td></td> <!-- trusted member -->
<td></td>
<td></td> <!-- editor -->
<td></td>
<th><sup>3</sup></th> <!-- moderator -->
<th><sup>2</sup><sup>3</sup></th>
<th></th> <!-- admin -->
<th></th>
<td></td> <!-- admin -->
<td></td>
</tr>
</tbody>
</table>

View File

@ -63,15 +63,7 @@ The process is as follows:
## Configuring
### Setting minimum and maximum Minetest versions
1. Open up the conf file for the package.
This will be `game.conf`, `mod.conf`, `modpack.conf`, or `texture_pack.conf`
depending on the content type.
2. Set `min_minetest_version` and `max_minetest_version` to the respective Minetest versions.
Eg:
min_minetest_version = 5.0
Also see [Package Configuration and Releases Guide](/help/package_config/).
See the [Package Configuration and Releases Guide](/help/package_config/) for
documentation on configuring the release creation.
You can set the min/max Minetest version from the Git repository, and also
configure what files are included.

View File

@ -10,14 +10,12 @@ ContentDB is for the community, and as such listings should be useful to the
community. To help with this, there are a few rules to improve the quality of
the listings and to combat abuse.
* No inappropriate content. <sup>2.1</sup>
* Content must be playable/useful, but not necessarily finished. <sup>2.2</sup>
* Don't use the name of another mod unless your mod is a fork or reimplementation. <sup>3</sup>
* Licenses must allow derivatives, redistribution, and must not discriminate. <sup>4</sup>
* Don't put promotions or advertisements in package listings, except for
donation and personal website links which are permitted in the
long description. <sup>5</sup>
* The ContentDB admin reserves the right to remove packages for any reason,
* **No inappropriate content.** <sup>2.1</sup>
* **Content must be playable/useful, but not necessarily finished.** <sup>2.2</sup>
* **Don't use the name of another mod unless your mod is a fork or reimplementation.** <sup>3</sup>
* **Licenses must allow derivatives, redistribution, and must not discriminate.** <sup>4</sup>
* **Don't put promotions or advertisements in any package metadata.** <sup>5</sup>
* **The ContentDB admin reserves the right to remove packages for any reason**,
including ones not covered by this document, and to ban users who abuse
this service. <sup>1</sup>
@ -27,8 +25,6 @@ the listings and to combat abuse.
The ContentDB admin reserves the right to remove packages for any reason,
including ones not covered by this document, and to ban users who abuse this service.
Also see the [help page on tags](/help/package_tags/).
## 2. Accepted Content
@ -39,15 +35,15 @@ Sexually-orientated content is not permitted.
Mature content, including that relating to drugs, excessive gore, violence, or
excessive horror, is not currently permitted - but will be in the future.
The submission of malware is strictly prohibited. This includes software which
does not do as it advertises, for example if it posts telemetry without stating
The submission of malware is strictly prohibited. This includes software that
does not do as it advertises, for example, if it posts telemetry without stating
clearly that it does in the package meta.
### 2.2. State of Completion
ContentDB should only currently contain playable content - content which is
sufficiently complete to be useful to end users. It's fine to add stuff which
is still a work in progress (WIP) as long as it adds sufficient value -
sufficiently complete to be useful to end-users. It's fine to add stuff which
is still a Work in Progress (WIP) as long as it adds sufficient value -
MineClone 2 is a good example of a WIP package which may break between releases
but still has value. Note that this doesn't mean that you should add a thing
you started working on yesterday, it's worth adding all the basic stuff to
@ -63,7 +59,7 @@ libraries allows them to be installed when a mod depends on it.
### 3.1 Right to a name
The first package to use a name based on the creation of its forum topic or
contentdb submission has the right to the technical name. The use of a package
ContentDB submission has the right to the technical name. The use of a package
on a server or in private doesn't reserve its name. No other packages of the same
type may use the same name, except for the exception given by 3.2.
@ -79,7 +75,7 @@ We reserve the right to issue exceptions for this where we feel necessary.
### 3.2. Mod Forks and Reimplementations
An exception to the above is that mods are allowed to have the same name as a
mod if its a fork of that mod (or a close reimplementation). In real terms, it
mod if it's a fork of that mod (or a close reimplementation). In real terms, it
should be possible to use the new mod as a drop-in replacement.
We reserve the right to decide whether a mod counts as a fork or
@ -93,9 +89,9 @@ reimplementation of the mod that owns the name.
Please ensure that you correctly credit any resources (code, assets, or otherwise)
that you have used in your package.
**The use of licenses which do not allow derivatives or redistribution is not
**The use of licenses that do not allow derivatives or redistribution is not
permitted. This includes CC-ND (No-Derivatives) and lots of closed source licenses.
The use of licenses which discriminate between groups of people or forbid the use
The use of licenses that discriminate between groups of people or forbid the use
of the content on servers or singleplayer is also not permitted.**
However, closed sourced licenses are allowed if they allow the above.
@ -108,15 +104,19 @@ of the [Free Software Foundation](https://www.gnu.org/philosophy/free-sw.en.html
### 4.2. Recommended Licenses
It is highly recommended that you use a free and open source software license.
FOSS licenses result in a sharing community and will increase the number of potential users your package has.
Using a closed source license will result in your package being massively penalised in the search results and package lists.
It is highly recommended that you use a Free and Open Source software (FOSS)
license. FOSS licenses result in a sharing community and will increase the
number of potential users your package has. Using a closed source license will
result in your package being massively penalised in the search results and
package lists. See the help page on [non-free licenses](/help/non_free/) for more
information.
It is recommended that you use a proper license for code with a warranty
disclaimer, such as the (L)GPL or MIT. You should also use a proper media license
for media, such as a Creative Commons license.
The use of WTFPL is discouraged as it doesn't contain a [valid warranty disclaimer](https://cubicspot.blogspot.com/2017/04/wtfpl-is-harmful-to-software-developers.html),
The use of WTFPL is discouraged as it doesn't contain a
[valid warranty disclaimer](https://cubicspot.blogspot.com/2017/04/wtfpl-is-harmful-to-software-developers.html),
and also includes swearing which prevents settings like schools from using your content.
[Read more](/help/wtfpl/).
@ -125,7 +125,7 @@ Public domain is not a valid license in many countries, please use CC0 or MIT in
## 5. Promotions and Advertisements (inc. asking for donations)
You may note place any promotions or advertisements in any meta data including
You may not place any promotions or advertisements in any meta data including
screenshots. This includes asking for donations, promoting online shops,
or linking to personal websites and social media. Please instead use the
fields provided on your user profile page to place links to websites and

View File

@ -134,3 +134,13 @@ pre code {
-webkit-box-shadow: 0 0 0 0.2rem rgba(231, 76, 60, 0.5);
box-shadow: 0 0 0 0.2rem rgba(231, 76, 60, 0.5);
}
.ranks-table tr {
th, td {
text-align: center;
}
td:first-child, th:first-child {
text-align: left;
}
}

View File

@ -7,7 +7,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{% block title %}title{% endblock %} - {{ config.USER_APP_NAME }}</title>
<link rel="stylesheet" type="text/css" href="/static/bootstrap.css">
<link rel="stylesheet" type="text/css" href="/static/custom.css?v=13">
<link rel="stylesheet" type="text/css" href="/static/custom.css?v=14">
<link rel="search" type="application/opensearchdescription+xml" href="/static/opensearch.xml" title="ContentDB" />
<link rel="shortcut icon" href="/favicon-16.png" sizes="16x16">
<link rel="icon" href="/favicon-128.png" sizes="128x128">