From d76f10c31281ded60b7d82bf81383b36f5813da8 Mon Sep 17 00:00:00 2001 From: rubenwardy Date: Wed, 16 Sep 2020 23:32:24 +0100 Subject: [PATCH] Improve documentation --- app/blueprints/metrics/__init__.py | 2 +- app/flatpages/help.md | 12 +- app/flatpages/help/content_flags.md | 11 +- app/flatpages/help/non_free.md | 8 +- app/flatpages/help/package_config.md | 34 ++- app/flatpages/help/ranks_permissions.md | 372 ++++++++++++------------ app/flatpages/help/release_webhooks.md | 16 +- app/flatpages/policy_and_guidance.md | 46 +-- app/scss/custom.scss | 10 + app/templates/base.html | 2 +- 10 files changed, 271 insertions(+), 242 deletions(-) diff --git a/app/blueprints/metrics/__init__.py b/app/blueprints/metrics/__init__.py index 4588ef2..48f0bc2 100644 --- a/app/blueprints/metrics/__init__.py +++ b/app/blueprints/metrics/__init__.py @@ -15,7 +15,7 @@ # along with this program. If not, see . 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__) diff --git a/app/flatpages/help.md b/app/flatpages/help.md index 456f2bb..f068a48 100644 --- a/app/flatpages/help.md +++ b/app/flatpages/help.md @@ -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) diff --git a/app/flatpages/help/content_flags.md b/app/flatpages/help/content_flags.md index 733ccb8..c3b5071 100644 --- a/app/flatpages/help/content_flags.md +++ b/app/flatpages/help/content_flags.md @@ -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. diff --git a/app/flatpages/help/non_free.md b/app/flatpages/help/non_free.md index 8eb1eb2..2641a0a 100644 --- a/app/flatpages/help/non_free.md +++ b/app/flatpages/help/non_free.md @@ -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 diff --git a/app/flatpages/help/package_config.md b/app/flatpages/help/package_config.md index 13db160..c518e89 100644 --- a/app/flatpages/help/package_config.md +++ b/app/flatpages/help/package_config.md @@ -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 + + 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): diff --git a/app/flatpages/help/ranks_permissions.md b/app/flatpages/help/ranks_permissions.md index 94af9a3..b03a7cd 100644 --- a/app/flatpages/help/ranks_permissions.md +++ b/app/flatpages/help/ranks_permissions.md @@ -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 - +
- - - - - - + + + + + + @@ -41,228 +41,228 @@ title: Ranks and Permissions - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - - - - + + + + + + + + + - - + + - - - - - - - - - + + + + + + + + + - - + + - - - - - - - - + + + + + + + + - - + +
RankNew MemberMemberTrusted MemberEditorModeratorAdminNew MemberMemberTrustedEditorModeratorAdmin
Owner of thing
Create Package✓ ✓ ✓ ✓ ✓✓ ✓✓ ✓✓ ✓ ✓ ✓ ✓✓ ✓✓ ✓
Approve Package ✓ ✓✓ ✓✓ ✓ ✓ ✓✓ ✓✓ ✓
Delete Package ✓ ✓✓ ✓✓ ✓ ✓ ✓ ✓ ✓✓ ✓✓ ✓
Edit Package ✓ ✓ ✓ ✓✓ ✓✓ ✓ ✓ ✓ ✓ ✓✓ ✓✓ ✓
Edit Maintainers✓ ✓ ✓ ✓ ✓ ✓✓ ✓✓ ✓ ✓ ✓ ✓ ✓✓ ✓
Add/Delete Screenshot✓ ✓ ✓ ✓ ✓✓ ✓✓ ✓✓ ✓ ✓ ✓ ✓✓ ✓✓ ✓
Approve Screenshot ✓ ✓ ✓✓ ✓✓ ✓ ✓ ✓ ✓✓ ✓✓ ✓
Make Release✓ ✓ ✓ ✓ ✓✓ ✓✓ ✓✓ ✓ ✓ ✓ ✓✓ ✓✓ ✓
Approve Release ✓ ✓ ✓✓ ✓✓ ✓ ✓ ✓ ✓✓ ✓✓ ✓
Change Release URL ✓ ✓ ✓ ✓
See Private Thread✓ ✓ ✓ ✓ ✓✓ ✓✓ ✓✓ ✓ ✓ ✓ ✓✓ ✓✓ ✓
Edit Comments ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Set Email✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓2✓ ✓✓ ✓
Create Token ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓2✓ ✓✓ ✓
Set Rank ✓3 ✓23✓ ✓✓ ✓
diff --git a/app/flatpages/help/release_webhooks.md b/app/flatpages/help/release_webhooks.md index b8ee785..24ab150 100644 --- a/app/flatpages/help/release_webhooks.md +++ b/app/flatpages/help/release_webhooks.md @@ -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. diff --git a/app/flatpages/policy_and_guidance.md b/app/flatpages/policy_and_guidance.md index 02232de..b069dea 100644 --- a/app/flatpages/policy_and_guidance.md +++ b/app/flatpages/policy_and_guidance.md @@ -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. 2.1 -* Content must be playable/useful, but not necessarily finished. 2.2 -* Don't use the name of another mod unless your mod is a fork or reimplementation. 3 -* Licenses must allow derivatives, redistribution, and must not discriminate. 4 -* Don't put promotions or advertisements in package listings, except for - donation and personal website links which are permitted in the - long description. 5 -* The ContentDB admin reserves the right to remove packages for any reason, +* **No inappropriate content.** 2.1 +* **Content must be playable/useful, but not necessarily finished.** 2.2 +* **Don't use the name of another mod unless your mod is a fork or reimplementation.** 3 +* **Licenses must allow derivatives, redistribution, and must not discriminate.** 4 +* **Don't put promotions or advertisements in any package metadata.** 5 +* **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. 1 @@ -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 diff --git a/app/scss/custom.scss b/app/scss/custom.scss index e16a75c..523b2ea 100644 --- a/app/scss/custom.scss +++ b/app/scss/custom.scss @@ -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; + } +} diff --git a/app/templates/base.html b/app/templates/base.html index c9be4a2..239cbe4 100644 --- a/app/templates/base.html +++ b/app/templates/base.html @@ -7,7 +7,7 @@ {% block title %}title{% endblock %} - {{ config.USER_APP_NAME }} - + -- 2.44.0