mirror of
https://github.com/evennia/evennia.git
synced 2026-03-18 13:56:30 +01:00
265 lines
No EOL
15 KiB
HTML
265 lines
No EOL
15 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html>
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>Guidelines for Evennia contribs — Evennia latest documentation</title>
|
||
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script src="../_static/jquery.js"></script>
|
||
<script src="../_static/underscore.js"></script>
|
||
<script src="../_static/doctools.js"></script>
|
||
<script src="../_static/language_data.js"></script>
|
||
<link rel="shortcut icon" href="../_static/favicon.ico"/>
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="next" title="AWSstorage system" href="Contrib-AWSStorage.html" />
|
||
<link rel="prev" title="Contribs" href="Contribs-Overview.html" />
|
||
</head><body>
|
||
|
||
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="Contrib-AWSStorage.html" title="AWSstorage system"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="Contribs-Overview.html" title="Contribs"
|
||
accesskey="P">previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="../index.html">Evennia latest</a> »</li>
|
||
<li class="nav-item nav-item-1"><a href="Contribs-Overview.html" accesskey="U">Contribs</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Guidelines for Evennia contribs</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
|
||
<div class="documentwrapper">
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<p class="logo"><a href="../index.html">
|
||
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
|
||
</a></p>
|
||
<div id="searchbox" style="display: none" role="search">
|
||
<h3 id="searchlabel">Quick search</h3>
|
||
<div class="searchformwrapper">
|
||
<form class="search" action="../search.html" method="get">
|
||
<input type="text" name="q" aria-labelledby="searchlabel" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
</div>
|
||
<script>$('#searchbox').show(0);</script>
|
||
<h3><a href="../index.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Guidelines for Evennia contribs</a><ul>
|
||
<li><a class="reference internal" href="#what-is-suitable-for-a-contrib">What is suitable for a contrib?</a></li>
|
||
<li><a class="reference internal" href="#layout-of-a-contrib">Layout of a contrib</a></li>
|
||
<li><a class="reference internal" href="#submitting-a-contrib">Submitting a contrib</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="Contribs-Overview.html"
|
||
title="previous chapter">Contribs</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="Contrib-AWSStorage.html"
|
||
title="next chapter">AWSstorage system</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<!--h3>This Page</h3-->
|
||
<ul class="this-page-menu">
|
||
<li><a href="../_sources/Contribs/Contribs-Guidelines.md.txt"
|
||
rel="nofollow">Show Page Source</a></li>
|
||
</ul>
|
||
</div><h3>Links</h3>
|
||
<ul>
|
||
<li><a href="https://www.evennia.com/docs/latest/index.html">Documentation Top</a> </li>
|
||
<li><a href="https://www.evennia.com">Evennia Home</a> </li>
|
||
<li><a href="https://github.com/evennia/evennia">Github</a> </li>
|
||
<li><a href="http://games.evennia.com">Game Index</a> </li>
|
||
<li>
|
||
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
|
||
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
|
||
<a href="https://evennia.blogspot.com/">Blog</a>
|
||
</li>
|
||
</ul>
|
||
<h3>Doc Versions</h3>
|
||
<ul>
|
||
|
||
<li><a href="Contribs-Guidelines.html">latest (main branch)</a></li>
|
||
|
||
<li><a href="../../3.x/index.html">v3.0.0 branch (outdated)</a></li>
|
||
|
||
<li><a href="../../2.x/index.html">v2.0.0 branch (outdated)</a></li>
|
||
|
||
<li><a href="../../1.x/index.html">v1.0.0 branch (outdated)</a></li>
|
||
|
||
<li><a href="../../0.x/index.html">v0.9.5 branch (outdated)</a></li>
|
||
|
||
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section class="tex2jax_ignore mathjax_ignore" id="guidelines-for-evennia-contribs">
|
||
<h1>Guidelines for Evennia contribs<a class="headerlink" href="#guidelines-for-evennia-contribs" title="Permalink to this headline">¶</a></h1>
|
||
<p>Evennia has a <a class="reference internal" href="Contribs-Overview.html"><span class="doc std std-doc">contrib</span></a> directory which contains optional, community-shared code organized by category. Anyone is welcome to contribute.</p>
|
||
<section id="what-is-suitable-for-a-contrib">
|
||
<h2>What is suitable for a contrib?<a class="headerlink" href="#what-is-suitable-for-a-contrib" title="Permalink to this headline">¶</a></h2>
|
||
<ul class="simple">
|
||
<li><p>In general, you can contribute anything that you think may be useful to another developer. Unlike the ‘core’ Evennia, contribs can also be highly game-type-specific.</p></li>
|
||
<li><p>Very small or incomplete snippets of code (e.g. meant to paste into some other code) are better shared as a post in the <a class="reference external" href="https://github.com/evennia/evennia/discussions/2488">Community Contribs & Snippets</a> discussion forum category.</p></li>
|
||
<li><p>If your code is intended <em>primarily</em> as an example or to show a concept/principle rather than a working system, consider if it may be better to instead <a class="reference internal" href="../Contributing-Docs.html"><span class="doc std std-doc">contribute to the documentation</span></a> by writing a new tutorial or howto.</p></li>
|
||
<li><p>If possible, try to make your contribution as genre-agnostic as possible and assume
|
||
your code will be applied to a very different game than you had in mind when creating it.</p></li>
|
||
<li><p>The contribution should preferably work in isolation from other contribs (only make use of core Evennia) so it can easily be dropped into use. If it does depend on other contribs or third-party modules, these must be clearly documented and part of the installation instructions.</p></li>
|
||
<li><p>If you are unsure about if your contrib idea is suitable or sound, <em>ask in discussions or chat before putting any work into it</em>. We are, for example, unlikely to accept contribs that require large modifications of the game directory structure.</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="layout-of-a-contrib">
|
||
<h2>Layout of a contrib<a class="headerlink" href="#layout-of-a-contrib" title="Permalink to this headline">¶</a></h2>
|
||
<ul class="simple">
|
||
<li><p>The contrib must be contained only within a single folder under one of the contrib categories below. Ask if you are unsure which category fits best for your contrib.</p></li>
|
||
</ul>
|
||
<table class="colwidths-auto docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p></p></th>
|
||
<th class="head"><p></p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">base_systems/</span></code></p></td>
|
||
<td><p><em>Systems that are not necessarily tied to a specific in-game mechanic but which are useful for the game as a whole. Examples include login systems, new command syntaxes, and build helpers.</em></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">full_systems/</span></code></p></td>
|
||
<td><p><em>‘Complete’ game engines that can be used directly to start creating content without no further additions (unless you want to).</em></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">game_systems/</span></code></p></td>
|
||
<td><p><em>In-game gameplay systems like crafting, mail, combat and more. Each system is meant to be adopted piecemeal and adopted for your game. This does not include roleplaying-specific systems, those are found in the <code class="docutils literal notranslate"><span class="pre">rpg</span></code> category.</em></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">grid/</span></code></p></td>
|
||
<td><p><em>Systems related to the game world’s topology and structure. Contribs related to rooms, exits and map building.</em></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">rpg/</span></code></p></td>
|
||
<td><p><em>Systems specifically related to roleplaying and rule implementation like character traits, dice rolling and emoting.</em></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">tutorials/</span></code></p></td>
|
||
<td><p><em>Helper resources specifically meant to teach a development concept or to exemplify an Evennia system. Any extra resources tied to documentation tutorials are found here. Also the home of the Tutorial-World and Evadventure demo codes.</em></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">tools/</span></code></p></td>
|
||
<td><p><em>Miscellaneous tools for manipulating text, security auditing, and more.</em></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<ul>
|
||
<li><p>The folder (package) should be on the following form:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span><span class="o">/</span>
|
||
<span class="n">contrib</span><span class="o">/</span>
|
||
<span class="n">category</span><span class="o">/</span> <span class="c1"># rpg/, game_systems/ etc</span>
|
||
<span class="n">mycontribname</span><span class="o">/</span>
|
||
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
||
<span class="n">README</span><span class="o">.</span><span class="n">md</span>
|
||
<span class="n">module1</span><span class="o">.</span><span class="n">py</span>
|
||
<span class="n">module2</span><span class="o">.</span><span class="n">py</span>
|
||
<span class="o">...</span>
|
||
<span class="n">tests</span><span class="o">.</span><span class="n">py</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>It’s often a good idea to import useful resources in <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> to make it easier to import them.</p>
|
||
</li>
|
||
<li><p>Your code should abide by the <a class="reference internal" href="../Coding/Evennia-Code-Style.html"><span class="doc std std-doc">Evennia Style Guide</span></a>. Write it to be easy to read.</p></li>
|
||
<li><p>Your contribution <em>must</em> be covered by <a class="reference internal" href="../Coding/Unit-Testing.html"><span class="doc std std-doc">unit tests</span></a>. Put your tests in a module <code class="docutils literal notranslate"><span class="pre">tests.py</span></code> under your contrib folder (as seen above) - Evennia will find them automatically. Use a folder <code class="docutils literal notranslate"><span class="pre">tests/</span></code> to group your tests if there are many of them across multiple modules.</p></li>
|
||
<li><p>The <code class="docutils literal notranslate"><span class="pre">README.md</span></code> file will be parsed and converted into a document linked from <a class="reference internal" href="Contribs-Overview.html"><span class="doc std std-doc">the contrib overview page</span></a>. It needs to be on the following form:</p>
|
||
<div class="highlight-markdown notranslate"><div class="highlight"><pre><span></span><span class="gh"># MyContribName</span>
|
||
|
||
Contribution by <yourname>, <year>
|
||
|
||
A paragraph (can be multi-line)
|
||
summarizing the contrib (required)
|
||
|
||
Optional other text
|
||
|
||
<span class="gu">## Installation</span>
|
||
|
||
Detailed installation instructions for using the contrib (required)
|
||
|
||
<span class="gu">## Usage</span>
|
||
|
||
<span class="gu">## Examples</span>
|
||
|
||
etc.
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<blockquote>
|
||
<div><p>The credit and first paragraph-summary will be automatically included on the Contrib overview page index for each contribution, so it needs to be just on this form.</p>
|
||
</div></blockquote>
|
||
</section>
|
||
<section id="submitting-a-contrib">
|
||
<h2>Submitting a contrib<a class="headerlink" href="#submitting-a-contrib" title="Permalink to this headline">¶</a></h2>
|
||
<aside class="sidebar">
|
||
<p class="sidebar-title">Not all PRs can be accepted</p>
|
||
<p>While most PRs get merged, this is not guaranteed: Merging a contrib means the Evennia project takes on the responsibility of maintaining and supporting the new code. For various reasons this may be deemed unfeasible.</p>
|
||
<p>If your code were to <em>not</em> be accepted for some reason, we can still link it from our links page; it can also be posted in our discussion forum.</p>
|
||
</aside>
|
||
<ul class="simple">
|
||
<li><p>A contrib must always be presented <a class="reference internal" href="../Coding/Version-Control.html#contributing-to-evennia"><span class="std std-doc">as a pull request</span></a> (PR).</p></li>
|
||
<li><p>PRs are reviewed so don’t be surprised (or disheartened) if you are asked to modify or change your code before it can be merged. Your code can end up going through several iterations before it is accepted.</p></li>
|
||
<li><p>To make the licensing situation clear we assume all contributions are released with the same <a class="reference internal" href="../Licensing.html"><span class="doc std std-doc">license as Evennia</span></a>. If this is not possible for some reason, talk to us and we’ll handle it on a case-by-case basis.</p></li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="Contrib-AWSStorage.html" title="AWSstorage system"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="Contribs-Overview.html" title="Contribs"
|
||
>previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="../index.html">Evennia latest</a> »</li>
|
||
<li class="nav-item nav-item-1"><a href="Contribs-Overview.html" >Contribs</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Guidelines for Evennia contribs</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
|
||
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2023, The Evennia developer community.
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
|
||
</div>
|
||
</body>
|
||
</html> |