Submitting changes for review and inclusion in 0 A.D. is easy if you are familiar with pull requests on the large git forges. We use Gitea's pull request system, which is similar to Github's. If you are not too familiar with git, this page contains a few pointers, and you are very welcome to ask questions on IRC.
Making some changes
First you should check out the game code from git and make some changes.
Ideally, those changes are already described in one of our issues, so you know it is wanted. It would be a shame if you put some effort in a code that we actually don't want. If your change is a feature, it needs to have an issue associated so we can discuss whether the feature is wanted and how. If it is a bugfix or a tiny change in the code, it's not mandatory to create a new issue.
Make sure you're on the latest version of the code (and merged in your own changes) when making your patch. And try to follow the coding conventions.
If this is your first contribution, please add yourself to the relevant file under binaries/data/mods/public/gui/credits/texts. You are free to use your real name, your nickname or both.
Always try to keep your patches reasonable. Different bugs shouldn't be mixed in the same patch.
When you modify or add methods to simulation components, you should add unit tests that test all added or modified changes.
Contribution flow
Overview
On the main repository, we follow the Trunk-Based Development Model (https://trunkbaseddevelopment.com). We enforce a linear history in the main branch: whenever a commit is merged, it is placed just ahead of the latest commit, without a merge commit.
When submitting contributions, you will craft a commit containing your changes, with the help of reviewers. At the end of the review process, your commit will have to be atomic (only contain a single and complete unit of work), its commit message will have to be informative, and its changes must be based on the latest version of the code. All of this means you will need to rewrite the history of the branch where you are developing your work.
Contribution steps
You must first create an account here on Gitea. Then, you must fork the 0ad/0ad repository under your account. Clone your fork to your computer, or, if you already cloned the main repository, locally add your fork as a remote using the command git remote add.
Setup your committer name and email using git config user.name and git config user.email.
- For the name, the easiest is to match your Gitea username.
- For the email, make sure that your committer email address matches one of your Gitea email address and that it is OK to make it public. If you do not wish to publish an email address, you can use
git config user.email "username@giteauser"so that Gitea recognizes your account. We provide@wildfiregames.comemail redirections for WFG team members.
When you are done making changes in your local repository:
- create a branch if you have not done so yet (
git switch -c) - add your changes to the staging area (
git add) - create a commit with your changes (
git commit) - This commit is supposed to be eventually included as-is in the main repository, so its commit message should be informative without needing extra context. We will help you improve that message during the review if needed. - push your branch to your fork of the repository (
git push)
Lastly, you can open a pull request on the main repository. Either use the "New Pull Request" button on the PR page, or click the "New Pull Request" small icon, next to the branch name, in your fork.
If there exists a related issue, please:
- change the issue Milestone from Backlog to Work In Progress, if relevant. The Release milestones are meant to plan our next version, so don't touch them. When the ticket is closed as fixed, we will change the Milestone from Work In Progress to the upcoming release.
- set a reference to your branch/pull request on the issue
At any point in the review process, it is advisable to drop on the IRC channel to discuss your code or just to chat with us.
How to prepare your contributions for merging
During the review process, your branch will accumulate changes and improvements until it is ready to be merged. It will then be time to rebase your work on top of all the changes made in the main branch; and to squash your work into one or several atomic commits. To reiterate, we want to avoid merge commits (with multiple parents) in the history. This restriction can only be lifted for very large changes, that need to be split up, but that also require an overarching merge commit documenting the change.
Several commands will be useful to you in this process.
git commit --amendallows you to add staged changes to your commit, or just to rewrite your commit message.git rebaseallows you to rebase your work on top of the main branch.git rebase -i("interactive rebase") is a more powerful version of the tool, which allows you to squash your commits together, to edit your commits, to drop faulty changes, etc., while rebasing your work.
A more detailed overview of these tools can be found in the Git tutorial Rewriting History.
All of those commands rewrite the history of your branch, so, in order to push it to Gitea, it will now be necessary to use "force-pushing", with the syntax git push --force.
Legal disclaimer
By sending in a patch, you agree that it is your own work (or else make it clear where it came from) and agree to licensing any code as GPL 2+ (or in some cases MIT, especially for code in lib/ - check the existing copyright headers on the source files you edit) and data files as CC-BY-SA 3.0.
See also the Terms of Use.
Patch review
Upon uploading the patch, an automated build, along with a number of tests, will be run on your change. Wait for them to complete and, if it fails, try to address the issue. Whatever it is successful or you need some help, don't hesitate to come discuss your patch with us over IRC.
We try to assign reviewers to pull requests as soon as possible. The list of PRs without an assigned reviewer should stay as empty as possible.
Some patches can take longer to review due to high complexity, lower priority or other circumstances. But it's best to keep in touch with us and ask for reviews.
Anyone can review any patch, even if you are not assigned! By the way, while your patch awaits for review, and if you are interested in contributing, you are encouraged to review other people's patches. We have review guidelines at ReviewingPatches, and you can also just test the patches.
Reviewers will test your patch and give you comments. When it is ready, it should be committed. However it is not the end of the journey! If we discover later that your patch had a hidden flaw, we will ask you to work on a fix. Usually, the reviewer who accepted your patch will contact you.
Dangling contributions from the previous workflows
Our review workflow evolved over the past couple years and we have some SVN patches as issue attachments, and a huge lot of SVN Differentials on Phabricator. Please read the Phabricator page to learn how to salvage open diffs.