How To Contribute And Get Help

If you cannot find what you are looking for in the documentation, here’s what to do:

  • If you need help, want to start a discussion or get some input on something you are working on, make a post to the discussions forum.

  • If you want more direct discussions with developers and other users, drop into our very friendly Discord channel.

  • If you think the documentation is not clear enough, create a documentation issue

  • If you have trouble with a missing feature or a problem you think is a bug, request or report it.

Community and Spreading the word

Being active and helpful in the forums or chat is already a big help.

Consider writing about Evennia on your blog or in your favorite (relevant) forum. Write a review somewhere (good or bad, we like feedback either way). Rate it on listings. Talk about it to your friends … that kind of thing.

Help with Documentation

Evennia depends heavily on good documentation and we are always looking for extra eyes and hands to improve it. Even small things such as fixing typos are a great help!

  • Easiest is to just report documentation issues as you find them. If we don’t know about them, we can’t fix them!

  • If you want to help edit the docs directly, check here on how to do it.

  • If you have knowledge to share, how about writing a new Tutorial?

Helping with code

If you find bugs, or have a feature-request, make an issue for it. If it’s not in an issue, the issue will most likely be forgotten.

Even if you don’t feel confident with tackling a bug or feature, just correcting typos, adjusting formatting or simply using the thing and reporting when stuff doesn’t make sense helps us a lot.

  • The code itself should follow Evennia’s Code style guidelines both for code and documentation. You should write code for that others can read an understand.

  • Before merging, your code will be reviewed. Merging of your code into Evennia is not guaranteed. Be ready to receive feedback and to be asked to make corrections or fix bugs or any documentation issues and possibly tests (this is normal and nothing to worry about).

Using a Forked reposity

The most elegant way to contribute code to Evennia is to use GitHub to create a fork of the Evennia repository and make your changes to that. Refer to the Forking Evennia version control instructions for detailed instructions.

Once you have a fork set up, you can not only work on your own game in a separate branch, you can also commit your fixes to Evennia itself.

  • Make separate branches for all Evennia additions you do - don’t edit your local master or develop branches directly. It will make your life a lot easier.

  • If you have a change that you think is suitable for the main Evennia repository, issue a Pull Request. This will let Evennia devs know you have stuff to share.

  • Bug fixes should generally be done against the master branch of Evennia, while new features/contribs should go into the develop branch. If you are unsure, just pick one and we’ll figure it out.

Contributing with Patches

To help with Evennia development it’s strongly recommended to do so using a forked repository as described above. But for small, well isolated fixes you are also welcome to submit your suggested Evennia fixes/addendums as a patch.

You can include your patch in an Issue or a Mailing list post. Please avoid pasting the full patch text directly in your post though, best is to use a site like Pastebin and just supply the link.

Making an Evennia contrib

Evennia has a contrib directory which contains user-shared code organized by category. You can contribute anything that you think may be useful to another dev, also highly game-specific code. A contrib must always be added via a forked repository.

Guidelines for making a contrib

  • If you are unsure about if your contrib idea is suitable or sound, ask in discussions or chat before putting any work into it. We are, for example, unlikely to accept contribs that require large modifications of the game directory structure.

  • If your code is intended primarily as an example or to show a concept/principle rather than a working system, you can add to the contribs/tutorials/ subfolder, but consider if it may be better to instead write a new tutorial doc page.

  • 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.

  • The contrib must be contained within a separate folder under one of the contrib categories (game_systems, rpg, utils etc). Ask if you are unsure which category to put your contrib under.

  • The folder (package) should be on the following form:

    mycontribname/
    __init__.py
    README.md
    module1.py
    module2.py
    ...
    tests.py

    It’s often a good idea to import useful resources in __init__.py to make it easier to access them (this may vary though).

    The README.md will be parsed and converted into a document linked from the contrib overview page. It should follow the following structure:

    # MyContribName

Contribution by <yourname>, <year>

A paragraph (can be multi-line)
summarizing the contrib (required)

Optional other text

## Installation

Detailed installation instructions for using the contrib (required)

## Usage

## Examples

etc.

    The credit and first paragraph-summary will be used on the index page. Every contrib’s readme must contain an installation instruction. See existing contribs for help.

  • If possible, try to make 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.

  • To make the licensing situation clear we assume all contributions are released with the same license as Evennia. If this is not possible for some reason, talk to us and we’ll handle it on a case-by-case basis.

  • Your contribution must be covered by unit tests. Put your tests in a module tests.py under your contrib folder - Evennia will find them automatically.

  • In addition to the normal review process, it’s worth noting that merging a contrib means the Evennia project takes on the responsibility of maintaining and supporting it. For various reasons this may be deemed beyond our manpower.

  • If your code were to not be accepted for some reason, you can ask us to instead link to your repo from our link page so people can find your code that way.

Donations

Evennia is a free, open-source project and any monetary donations you want to offer are completely voluntary. See it as a way of showing appreciation by dropping a few coins in the cup.

  • You can support Evennia as an Evennia patreon. A patreon donates a (usually small) sum every month to show continued support.

  • If a monthly donation is not your thing, you can also show your appreciation by doing a one-time donation (this is a PayPal link but you don’t need PayPal yourself to use it).