Welcome to the TGO repository! This document attempts to hit the high points of contributing to the codebase and should help you figure out how work through any confusion that might arise during the devoplment process.
Kind of!
You should definitely understand the golden rules:
- Don't commit to
releasebranch - Don't force push to
releaseortgo_dev
Otherwise mostly check out this section and chat with your lead to understand any discipline specific guidance.
If you or your lead have any questions drop by #tgo-programming. We're friendly and would love to help.
This is a large project! a full org chart is available here but some the relevant leads:
- envy — Engineering (that's us!)
- Stephen — Technical Narrative
- Mario — Game Design
- Keumars — Creative Director
- Maki — Lead Producer
If something is unclear at any point in time feel free to ask around #tgo-programming or contact someone from the production team / or a relevant team lead to help guide you to the correct person/place for more info.
While the whole TGO team is large our engineering team is small and it's likely we'll each end up owning major parts of the game and working in each other's domains if we want to make good time.
In order to maintain awareness of what's going on outside our eng focus we:
- have a weekly sync meeting. Notes are kept here
- track active work on a kanban board
- communicate regularly in the #tgo-programming channel
We hint at this above but it is likely each one of us will end up being the single biggest voice in the room for a one or more section of the code. Even so it explicitly does not mean that you will have to do all the related work on your own. It only means you are the person most likely to have a full understanding of the related systems and when we need more hands on a specific system it may fall to you to help understand how to decompose the problem or debug a particularly tricky issue.
As a team we should aim to:
- Never let somebody own something by accident or implicitly;
- Not silently abandon something that we own;
- Understand when something doesn't have an owner.
- GDScript should pass lint before merge. We have the repo set up to run a CI job
and check validity using
gdlint. More info can be found about the errors it reports and how to set up exclusions on the wiki. To manually run the linter see docs/docker.md. - GDScript should format test cleanly before merge. In order to reduce merge issues
we use an automated tool
gdformatto ensure our code conforms to a consistent formatting spec. Details on this are available on the wiki. To manually run the linter see docs/docker.md. - We currently require static typing and non-typed variable
declarations will be reported as an error. There are several benefits of this
- Code maintainability — static typing is a compiler-enforced contract of your intent. Its accuracy will never decay and it tells the future reader what to expect without requiring them to fully understand function internals;
- Transferability — a secret power of staticly typed codebases is the reduced cognitive load when trying to modify or contribute to code that you did not write. This is highly related to maintainability but is not the same;
- Reduced reliance on tests — building with a dynamically typed codebase means you can take many more liberties with your functions, how they're used, and how they behave. This means that the surface area for bugs / mistakes is larger and that the factors you need to consider when making changes is significantly higher and (often) not obvious. This can be totally fine but in order to have high confidence in behavior it requires an extremely solid test suite. Using a statically typed language helps ameliorate the surface area and means we can maintain high confidence on function behavior without as aggressive of a test suite;
- Performance — using statically typed gdscript is between 5 and 150% faster than dynamically typed code. And it can get better as VM optimizations are done by the Godot team.
Generally we will not be merging into the release branch going forward. It is
reserved for near release quality code that has passed basic testing and will
be going through a QA process for approval.
Sprint / feature work will be merged into this branch and it's where most active development will happen. A merge to tgo_dev should:
- first be presented as a PR with a meaningful description that will help reviewers understand the changes being made and provide meaningful commentary
- pass any CI tests that have been configured
- once approved the PR should be squashed instead of standard merge. This helps keep
the
tgo_devbranch clean and orderly
We understand this is a volunteer project and it may not always be possible for a PR to receive a full and thorough review in a timely manner. The suggested process when trying to merge new code to tgo_dev will be:
- Initiate the PR and do a self-review: re-read the code with an eye for things that may be done better, ensure CI passes, and provide a write-up for the changes being merged.
- Post a link to your PR in #tgo-programming and give folks ~48 hours to get a chance to read through it and provide feedback.
- If you haven't seen anybody indicate they've started looking at your review within 48h
feel free to post a note in channel and squash-merge it into
tgo_dev.
Notes / exceptions:
- For PRs that need an expedited review tag envy in #tgo-programming when you have a PR ready and we'll try to help make sure we can keep things speedy without compromising code quality.
- For minor changes (an, admittedly, subjective assessment) include a
[minor]indicator in your PR title and feel free to merge without the 48h waiting period but do go through the PR process & writeup so that we have a full history of what got merged and why - For particularly complicated / expansive changes please do not merge without review. If you need attention on the PR tag envy in #tgo-programming.
Most of above process is focused on GDScript and technical changes but at least initially the repository contains work including assets, dialogue, etc.
Those changes should be considered out of scope for this document and should follow a process appropriate for that discipline and defined by the corresponding lead.
This is not super well defined but when we merge a release candidate to release
any bugs found will be fixed in a RC branch cut off release.
As changes are made in that RC branch they should be back ported to tgo_dev. RC branches should not be merged back into release or subsequent tgo_dev->release merges will be problematic.
When doing development on a specific feature you should start your branch off the
most recent tgo_dev commit. As time passes your branch will fall "behind" the
tgo_dev branch off which it was based. As that happens it's suggested you
pull tgo_dev and then merge that into your branch. This helps reduce conflict
when it's time for your feature to be submitted to tgo_dev.
Generally speaking you should cut a new branch for each new feature and retire that branch when you have completed the work you were doing. For example if I wanted to implement a new feature for a level I would:
- branch off
tgo_devand give my branch the nameenvy-feature-name - do the work making commits as needed
- occasionally update my local view of
tgo_devand merge that intoenvy-feature-name - When I'm done I would create a new PR to merge
envy-feature-nameintotgo_dev - Once I have completed any PR feedback and gotten an approval to merge I would squash-merge that back into tgo_dev
- I would then delete the branch
envy-feature-namebecause it's all been submitted
If I wanted to do a new bit of development I would repeat the process but use a new branch name that accurately reflects what I'm working on.
There are essentially no rules on what you can do on your own branch.
The ./docs directory has a deep dive on various systems as well as broader
structural decisions.
Start here.