<h1>Guidelines for Evennia contribs<aclass="headerlink"href="#guidelines-for-evennia-contribs"title="Permalink to this headline">¶</a></h1>
<p>Evennia has a <aclass="reference internal"href="Contribs-Overview.html"><spanclass="doc std std-doc">contrib</span></a> directory which contains optional, community-shared code organized by category. Anyone is welcome to contribute.</p>
<sectionid="what-is-suitable-for-a-contrib">
<h2>What is suitable for a contrib?<aclass="headerlink"href="#what-is-suitable-for-a-contrib"title="Permalink to this headline">¶</a></h2>
<ulclass="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 <aclass="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 <aclass="reference internal"href="../Contributing-Docs.html"><spanclass="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>
<sectionid="layout-of-a-contrib">
<h2>Layout of a contrib<aclass="headerlink"href="#layout-of-a-contrib"title="Permalink to this headline">¶</a></h2>
<ulclass="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>
<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>
<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>
<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 <codeclass="docutils literal notranslate"><spanclass="pre">rpg</span></code> category.</em></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>
<p>It’s often a good idea to import useful resources in <codeclass="docutils literal notranslate"><spanclass="pre">__init__.py</span></code> to make it easier to import them.</p>
</li>
<li><p>Your code should abide by the <aclass="reference internal"href="../Coding/Evennia-Code-Style.html"><spanclass="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 <aclass="reference internal"href="../Coding/Unit-Testing.html"><spanclass="doc std std-doc">unit tests</span></a>. Put your tests in a module <codeclass="docutils literal notranslate"><spanclass="pre">tests.py</span></code> under your contrib folder (as seen above) - Evennia will find them automatically. Use a folder <codeclass="docutils literal notranslate"><spanclass="pre">tests/</span></code> to group your tests if there are many of them across multiple modules.</p></li>
<li><p>The <codeclass="docutils literal notranslate"><spanclass="pre">README.md</span></code> file will be parsed and converted into a document linked from <aclass="reference internal"href="Contribs-Overview.html"><spanclass="doc std std-doc">the contrib overview page</span></a>. It needs to be on the following form:</p>
Detailed installation instructions for using the contrib (required)
<spanclass="gu">## Usage</span>
<spanclass="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>
<sectionid="submitting-a-contrib">
<h2>Submitting a contrib<aclass="headerlink"href="#submitting-a-contrib"title="Permalink to this headline">¶</a></h2>
<asideclass="sidebar">
<pclass="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>
<ulclass="simple">
<li><p>A contrib must always be presented <aclass="reference internal"href="../Coding/Version-Control.html#contributing-to-evennia"><spanclass="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 <aclass="reference internal"href="../Licensing.html"><spanclass="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>
