+# {NAME} // name of the game
+
+- Home: {URL} // project main site(s) (most significant first)
+- Media: {URL} // (optional) links to wikipedia and other significant mentions
+- Inspiration: {XX} // (optional) names of games used as inspiration for this entry
+- State: {XX} // one of {beta, mature}, (optional) "inactive since YEAR"
+- Play: {URL} // (optional) link(s) to online play possibilities
+- Download: {URL} // (optional) link(s) to download binary (or source if no repository is given) releases
+- Platform: {XX} // (optional) list of supported platforms {Windows, Linux, macOS, Android, iOS, Web}
+- Keyword: {XX} // list of tags describing the game, first tage is the main category tag, at least one category tag needed
+- Code repository: {URL} // code repositories (most significant first)
+- Code language: {XX} // programming language(s) used
+- Code license: {XX} // license of the code, use "Custom" with comment in () if the license is project-specific
+- Code dependency: {XX} // (optional) important third party libraries / frameworks used by the project
+- Assets license: {XX} // (optional) license(s) of the assets (artwork, ..)
+- Developer: {XX} // (optional) list of developer names
+
+Notes // whatever you want to put up here, focused on the technical aspects
+
+## Building
+
+- Build system: {XX} // (optional) typically one of {CMake, Autoconf, Gradle, ..} but can be more
+- Build instruction: {XX} // (optional) link(s) to build instructions offered by the project
+
+Notes // addition build instructions or technical comments you want to put here
+
+
+### Important conventions (please read carefully!)
+
+- For the name of an entry file, use the name of the game, convert to lower case and replace spaces with underlines.
+ Example: "Alex the Allegator 4" is in file alex_the_allegator_4.md. In the case of a name collision just add something
+ to make file names unique.
+- If there are multiple links, licenses, ... separate them by comma.
+- The same link can be assigned to different fields (home could also be the code repository, etc.).
+- Put comments in "()" parentheses after each values.
+- Remove lines with fields that do not apply to the project or where information is not available otherwise.
+- Status active is implied/default unless the optional "inactive since" is present
+- All lines starting with '- ' are considered fields.
+- No need to add the number of stars/forks/founding year of Git repositories (GitHub, GitLab), that is done automatically regularly
+- No need to add or change any text starting with "@", unless you really know what to do.
+- No need to modify "code/archives.json", that will be overwritten regularly.
+- No need to modify "docs/**" or "entries/screenshots/*" or "entries/tocs/*"
+
+### Developer information
+
+The developer information relates developers to open source games they have participated in. Developer profiles on GitHub,
+SourceForge or BitBucket are linked on a developer information and also on the game entries in the developers field.
+The relation between developers and games is shown twice to allow for both search directions, i.e. find all developers of
+a game or all games of a developer. A consistency check will run regularly on the content and will give precedence to
+the developer names stored in the games entries (the games list stored in the developer information will be overwritten).
+
+It is recommended to suggest changes to developer information within an issue on the issue tracker although it's also
+possible to modify the [developers file](developers.md), if you know what you are doing. Please add missing developers only
+to the "Developer" field in an entry.
+
+### Inspiration information
+
+Inspirations are short pieces of information that collect links to inspirations website or Wikipedia websites and also
+link to all entries that have this game as inspiration. Please only edit entries "Inspiration" fields to indicate that a
+game has a certain inspiration. If not sure, suggest changes or additions to inspirations within an issue at the issue
+tracker (see above).
+
+### Updates to the code base
+
+All Python scripts reside in the code folder, their purpose is:
+
+- checking consistency of the contained entry, developer and inspiration information (maintenance_xxx.py)
+- reading and writing markdown files from and to Python dictionaries (with lark grammars *.lark)
+- keep a local set of git repositories of the games (archive_update.py)
+- synchronize with opensourcegameclones and LibreGameWiki (synchronization/*.py)
+- generate the static website that is stored in doc/* (code/html/generate_static_website.py via *.jinja templates)
+
+Help: [MarkDown Help](https://help.github.com/articles/github-flavored-markdown), [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
\ No newline at end of file
diff --git a/README.md b/README.md
index 743f30aa..6cab3f58 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,21 @@
# Open Source Games
-**Please visit the [Web page](https://trilarion.github.io/opensourcegames/), which renders the content of this list nicely!**
+**Please visit the [Web page](https://trilarion.github.io/opensourcegames/), which renders the content of this list
+nicely!**
-Development **[Blog](https://trilarion.blogspot.com/search/label/osgames)** / **[Statistics](statistics.md#statistics)** about entries
+Development **[Blog](https://trilarion.blogspot.com/search/label/osgames)** / **[Statistics](statistics.md#statistics)**
+/ **[Contribution](CONTRIBUTING.md)** guidelines
+
+OSGL (open source games list) is a list of open source games, game frameworks and game creation tools. The projects are at least in beta stage with a
+code basis that builds into an executable demo. The code must be under a [FOSS](https://en.wikipedia.org/wiki/FOSS)
+license that allows modification and sharing by others. For each entry, relevant information is collected regarding
+code repositories, download possibilities and build instructions.
+
+Alternatives include [Open Source Clones](https://github.com/opengaming/osgameclones);
+[Games hosted on GitHub](https://github.com/leereilly/games); [List of open-source video games](https://en.wikipedia.org/wiki/List_of_open-source_video_games)
+on Wikipedia, diverse [Awesome Gaming lists](https://github.com/sindresorhus/awesome#gaming) or the [LibreGameWiki](https://libregamewiki.org/Main_Page).
+
+## Content
[comment]: # (start of autogenerated content, do not edit)
**[Games](entries/tocs/_games.md#Games)** (1499) - **[Tools](entries/tocs/_tools.md#Tools)** (50) - **[Frameworks](entries/tocs/_frameworks.md#Frameworks)** (96) - **[Libraries](entries/tocs/_libraries.md#Libraries)** (16)
@@ -13,71 +26,24 @@ By platform: **[Windows](entries/tocs/_windows.md#windows)** (541), **[Linux](en
[comment]: # (end of autogenerated content)
-A list of open source games, game frameworks and game creation tools. The projects are at least in beta stage with a code basis that builds
-into an executable demo. The code must be under a [FOSS](https://en.wikipedia.org/wiki/FOSS) license that allows
-modification and sharing by others. For each entry, relevant information is collected regarding code repositories,
-download possibilities and build instructions.
-
-Similar collections include [Open Source Clones](https://github.com/opengaming/osgameclones) of popular games;
-Popular games, add-ons, maps, etc. [hosted on GitHub](https://github.com/leereilly/games); [List of open-source video games](https://en.wikipedia.org/wiki/List_of_open-source_video_games) on Wikipedia or the [LibreGameWiki](https://libregamewiki.org/Main_Page).
-
## Contribute
-To add or modify entries, please use the [Issue tracker](https://github.com/Trilarion/opensourcegames/issues),
-or fork this repository and submit a pull request.
-
-### Adding a new entry
-
-Checklist for a new entry
-
-- Must be a game, a game maker, a game's tool, a framework or a library, used in games
-- Must be under a FOSS license (GPL, MIT, ...) and code must be available
-- Must be mature or at least in beta (with an executable demo)
-- Active or inactive is irrelevant.
-
-All entries are stored as [markdown](https://en.wikipedia.org/wiki/Markdown) text with some specific conventions.
-Adding a new entry is as easy as modifying the [template](games/template.md) and adding the modified markdown file in a subdirectory of [games](games).
-
-Description of the fields in the template. Comments start with "//".
-
-
-# {NAME} // name of the game
+**See the [Contribution guidelines](CONTRIBUTING.md).**
-_{Description}_ // single description line (typically taken from about page of game)
-
-- Home: {URL} // project main site(s) (most significant first)
-- Media: {URL} // (optional) links to wikipedia and other significant mentions
-- State: {XX} // one of {beta, mature} and optional "inactive since YEAR"
-- Play: {URL} // (optional) link(s) to online play possibility
-- Download: {URL} // (optional) link(s) to download binary (or source) releases
-- Platform: {XX} // (optional) list of supported platforms {Linux, Windows, macOS, Android, ..}
-- Keywords: {XX} // list of tags describing the game, first tage is the main category tag
-- Code repository: {URL} // code repositories (most significant first)
-- Code language: {XX} // programming language(s) used
-- Code license: {XX} // license of the code, use "Custom" with comment in () if the license is project-specific
-- Code dependencies: {XX} // (optional) important third party libraries / frameworks used by the project
-- Assets license: {XX} // (optional) license(s) of the assets (artwork, ..)
-
-// whatever you want to put here
-
-## Building
-
-- Build system: {XX} // (optional) typically one of {CMake, Autoconf, Gradle, ..}
-- Build instructions: {URL} // (optional) link(s) to build instructions offered by the project
-
-// whatever you want to put here
-
+## License
-- If there are multiple links, licenses, ... separate them by comma.
-- The same link can be assigned to different fields (home could also be the code repository, etc.).
-- Put comments in "()" parentheses (do not put commas in comments).
-- Remove lines with fields that do not apply to the project or where information is not available otherwise.
-- Status active is implied/default unless the optional "inactive since" is present
-- All lines starting with '- ' are considered fields.
+See [LICENSE](LICENSE). This work is dedicated to the public domain by waiving all rights to the work worldwide under
+copyright law, including all related and neighboring rights, to the extent allowed by law. Additionally, the content is
+also licensed (multi-licensed) under the following other licenses: [WTFPL](http://www.wtfpl.net/txt/copying/),
+[CC-BY-3.0](https://creativecommons.org/licenses/by/3.0/), [GFDL 1.3](https://www.gnu.org/licenses/fdl-1.3.txt) and
+given to the Public Domain (wherever it exists and to the maximum possible extent). I hope that this allows everyone
+to just use the content however they like.
-Help: [MarkDown Help](https://help.github.com/articles/github-flavored-markdown), [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
+An exception are the screenshots (folders: entries/screenshots and docs/screenshots). They are taken from the respective
+projects and scaled down, just acting as thumbnails. Their use is considered fair use. However, for that reason they
+are excluded from the content license here.
-## Background
+### Background
I love open source projects and games and I am interested in learning more about building systems.
I see the following benefits of having this database.
@@ -87,15 +53,6 @@ I see the following benefits of having this database.
- Revival of abandoned games that do not build anymore
- Conversion of old repository formats like CVS to Git
-## Disclaimer
+### Disclaimer
-No warranty whatsoever of the information presented herein for any purpose. There could (will) be errors in here.
-
-## License
-
-See [LICENSE](LICENSE). This work is dedicated to the public domain by waiving all rights to the work worldwide under copyright law, including all related and neighboring rights, to the extent allowed by law.
-
-Additionally, the content is also licensed (multi-licensed) under the following other licenses: [WTFPL](http://www.wtfpl.net/txt/copying/), [CC-BY-3.0](https://creativecommons.org/licenses/by/3.0/),
-[GFDL 1.3](https://www.gnu.org/licenses/fdl-1.3.txt) and given to the Public Domain (wherever it exists and to the maximum possible extent).
-
-I hope that this does the trick. But really, just use the content however you like.
+No warranty whatsoever of the information presented herein for any purpose. There can (and will) be errors in here.
\ No newline at end of file
diff --git a/code/html/contribute.jinja b/code/html/contribute.jinja
index ce6b28a7..45ae4d18 100644
--- a/code/html/contribute.jinja
+++ b/code/html/contribute.jinja
@@ -1,36 +1,53 @@
{% extends "base.jinja" %}
{% block content %}
-Please help improve the content of this site. The preferred way to contribute or give feedback is:
+Improve or add entries, give feedback.
+Please help improve the content of this site or give feedback. The preferred actions are:
See also the Contribution guidelines on GitHub.
Entries for open source games, gaming engines and gaming tools are stored as human readable text version in a markdown format (example). - For each entry, the database content can be seen when clicking on "Raw entry" below the entry. You can suggest corrections or updates to an entry or a list of entries in one of the following ways:
-Entries for open source games, gaming engines and gaming tools are stored as human readable text version in a
+ markdown format (example).
+ For each entry, the database content can be seen when clicking on "Raw entry" below the entry. You can suggest
+ corrections or updates to an entry or a list of entries in one of the preferred way specified above (issue at the issue tracker
+ or GitHub pull request).
+ Please refer to the Contribution guidelines
+ before. For suggesting screenshots, please add a message to this issue.
The developer information is stored in a single big file (developer database) and relates developers to open source games they have participated in. Additionally, developer profiles on GitHub, SourceForge or BitBucket are linked on - a developer information and again on the game entries, in the developers field, all developers are listed. The relation between developers and games is stored twice to allow for both search directions, i.e. find all developers of a game or all games of a developer. - A consistency check will run regularly on the content and will give precedence to the developer names stored in the games entries (the games list stored in the developer information will be overwritten).
-The developer information relates developers to open source games they have participated in. Developer profiles + on GitHub, SourceForge or BitBucket are linked on a developer information and also on the game entries in the developers field. + Please suggest changes or additions to the developer section within an issue at the issue tracker (see above).
Inspirations are short pieces of information that collect links to inspirations website or Wikipedia websites + and also link to all entries that have this game as inspiration. Please only edit entries "Inspiration" fields to + indicate that a game has a certain inspiration. If not sure, suggest changes or additions to inspirations within + an issue at the issue tracker (see above).
Please help improve the content of this site. The preferred way to contribute or give feedback is:
+Improve or add entries, give feedback.
+Please help improve the content of this site or give feedback. The preferred actions are:
See also the Contribution guidelines on GitHub.
Entries for open source games, gaming engines and gaming tools are stored as human readable text version in a markdown format (example). - For each entry, the database content can be seen when clicking on "Raw entry" below the entry. You can suggest corrections or updates to an entry or a list of entries in one of the following ways:
-Entries for open source games, gaming engines and gaming tools are stored as human readable text version in a
+ markdown format (example).
+ For each entry, the database content can be seen when clicking on "Raw entry" below the entry. You can suggest
+ corrections or updates to an entry or a list of entries in one of the preferred way specified above (issue at the issue tracker
+ or GitHub pull request).
+ Please refer to the Contribution guidelines
+ before. For suggesting screenshots, please add a message to this issue.
The developer information is stored in a single big file (developer database) and relates developers to open source games they have participated in. Additionally, developer profiles on GitHub, SourceForge or BitBucket are linked on - a developer information and again on the game entries, in the developers field, all developers are listed. The relation between developers and games is stored twice to allow for both search directions, i.e. find all developers of a game or all games of a developer. - A consistency check will run regularly on the content and will give precedence to the developer names stored in the games entries (the games list stored in the developer information will be overwritten).
-The developer information relates developers to open source games they have participated in. Developer profiles + on GitHub, SourceForge or BitBucket are linked on a developer information and also on the game entries in the developers field. + Please suggest changes or additions to the developer section within an issue at the issue tracker (see above).
Inspirations are short pieces of information that collect links to inspirations website or Wikipedia websites + and also link to all entries that have this game as inspiration. Please only edit entries "Inspiration" fields to + indicate that a game has a certain inspiration. If not sure, suggest changes or additions to inspirations within + an issue at the issue tracker (see above).