How to contribute to Escoria

Thanks a lot for thinking about contributing to the Escoria project! Please read the guidelines outlined in this document on how to most efficiently add your contribution to the project to make it better.

How do you want to contribute?

Questions

Of course! We’ll help you to answer your question as best as possible. Our community uses Discord to communicate and collaborate.

Please simply join our server and state your question in our support channel:

https://img.shields.io/discord/884336424780984330.svg?label=Join%20our%20Discord&logo=Discord&colorB=7289da&style=for-the-badge

Bugs

Oh no! Sorry about that. We guess you encountered a bug. Please file an issue in the Escoria issue tracker.

I can also send code changes that will fix the bug.

Feature requests

Sure. We’re always open to new ideas. Please make sure you talk to our community in the Discord support channel first. Maybe somebody else already thought about the same thing and found a solution!

https://img.shields.io/discord/884336424780984330.svg?label=Join%20our%20Discord&logo=Discord&colorB=7289da&style=for-the-badge

If not, please add a new feature request in the Escoria issue tracker.

Please note that we’re developing Escoria in our free time and can’t always implement new features as fast as we would like to. We will usually add a version to your feature request stating when the feature can possibly be added to Escoria. This, however, might change, so don’t bet on it.

I can also send code changes that will implement the new feature.

Contributions

That’s awesome. Thanks a lot. Let’s talk about how we implement code in Escoria.

Code changes

We implement all new code in our demo game. That’s our testing ground, if you will. Clone the demo game’s git repository. Checkout the develop branch and then create a new branch named “issue-<your issue number>”. (e.g. issue-42)

If you’d like to submit code for fixing a bug, please recreate the bug in the demo game. If you want to implement a new feature, create a demo for the new feature in the game.

Afterwards, add the required code to fix the bug or implement the feature.

When committing in git, please make sure to format your commit message according to the semantic-release standard.

When you’re ready, please interactively rebase your branch and remove all non-essential commits from your changes. See this article for information about interactively rebasing.

Afterwards, open a pull request in the demo game repository against the develop branch. We may possibly ask you to kindly add more changes or otherwise communicate more about your changes. Please use the PR UI to answer these questions and resolve the conversations once you have implemented the requested change.

Again, thanks a lot for your contributions. ❤️ 🎁

Documentation changes

  • The documentation is written in the reStructeredText format https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

  • The documentation style is checked by doc8 https://pypi.org/project/doc8/

  • The API command documentation is automatically generated from the comments above the functions. Update the comments and submit a pull request as per the code changes process above. Once merged into the main repository, the documentation will be automatically updated by GitHub actions.

  • All other documentation is built from the file structure in the documentation repository.

doc8 will run to check the documentation meets the project’s style standards. Running doc8 locally before submitting a PR is highly encouraged.

Behind the scenes:

These details are provided for interest only - contributors will not need to concern themselves with how the documentation gets from code to the website.

After a successful pull request to the main repository, GitHub actions will run the following steps automatically :

  • extractesc.py will extract information about the ESC commands from the API documentation and make the documentation files in the API folder.

  • These are accessed by the main documentation from a reference in esc_reference.template.rst

  • doc8 will confirm the documentation meets the project’s style requirements by running .github/workflows/check-docs.yml