Contributing to Trosnoth
The Trosnoth source code repository can be accessed on Heptapod. You can clone the repository by clicking the Clone button at the top right of that page.
If you don't yet have a favourite Python editor, we recommend using PyCharm community edition. PyCharm gives you easy code navigation and static checking. We've even added some PyCharm project settings to the Trosnoth repo so you can easily spin up a Trosnoth server, play a Trosnoth solo game, or run the test suite.
Workflow for Contributing
We use Mercurial for version control. To contribute to Trosnoth, you'll need to follow these steps:
Ask for developer access to the Trosnoth project on Heptapod. To do this, create a ticket using the ‘discussion’ template, and say that you'd like to contribute.
Clone the Trosnoth repository:
hg clone ssh://firstname.lastname@example.org/games/trosnoth
Update to the branch or topic your changes will be based on (e.g.,
hg update default). As a general rule, most contributions should be based on
default. Only start from a different branch or topic if you are certain your change depends on that branch or topic.
Create a topic for your work. Mercurial topics allow you to create mutable draft changesets and safely rewrite (rebase, amend, etc.) them as needed even after you've pushed them. For more info on Mercurial topics, see this tutorial. You should name your topic
<your-name>-<feature>. For example,
hg topics talljosh-space-vampire-scenario.
If there's already a ticket on the issue tracker for the bug or feature you're working on, make sure you assign yourself to the issue. If there's not already a ticket, it's polite to create one and assign it to yourself, so that other people can see that you're working on it, and can use the ticket to communicate with you.
Once you've completed your work, create a merge request. Reference the related ticket in your merge request.
Note: until your topic has been accepted and merged into one of the main branches, the changesets will be mutable. This means that you can safely use Mercurial's history-rewriting operations on it. For more information on history rewriting, see this document.
While you're working, it's good practice to regularly pull and rebase your topic (
hg rebase; merging with
hg merge is also acceptable). This ensures that you're always working from the latest approved changesets.
Your changes will be easier to review (so probably accepted more quickly) if you separate distinct changes into distinct commits. For example, if you're writing a new scenario and you need to add a new
Event to the
Player class, you could have one commit which defines the new event and triggers the event, and a separate commit containing the new scenario class and adding it to the scenario registry. You can use
hg split to split a draft changeset into multiple commits after the fact.
Never commit changes to someone else's topic without their complete knowledge and consent—multiple people rewriting the history of the same topic can lead to situations that are complicated to resolve.
Please don't use history rewriting operations on changesets that someone else has authored, even if you're working on your own topic. Doing so would result in a changeset being attributed to someone else even though you have edited it. If you have an edit to make to someone else's draft work, either make a new commit with your edits, or ask the original author to amend their work. If you want to rebase someone else's work, use a merge instead, or ask the original author to rebase it.
- All bugs, feature proposals, and development discussions should take place on the issue tracker where possible. Please do your best to tag the ticket appropriately.
- Previously, ideas, brainstorming and feature requests were added to this page.
- Previously, work in progress by regular Trosnoth devs could be seen on the Trosnoth Trello board. At time of writing, not all of this has been transferred across to the Hetpapod issue tracker.
Once you've got your IDE set up, and cloned the repository, you'll need to install the dependencies. Dependencies for the development version of Trosnoth are:
- Python 3.8+
- Twisted (16.0 or newer)
- If on Windows, pywin32
To start to get an understanding of how Trosnoth works inside, read Getting Started. The following how-to guides explain the process of some Trosnoth coding you might find interesting: