Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
A guide for how to contribute to OpenRA if you aren't familiar with Git, GitHub, source control, or open source projects.
- "make test" might not be descriptive enough (provide a link to Compiling section, which may need improving?)
- A better explanation of pull request tags?
- Move images onto OpenRA's wiki (off imgur)
What you need
- A GitHub account (this website!)
- A Git client
- C# IDE (if you intend on modifying code)
GitHub account setup
TIP: If you are interested purely in compiling the code, and not contributing, feel free to skip to the Cloning step, replacing
OpenRA, then skip to the Compiling section.
The first step for new contributors is to fork the OpenRA repository. Forking creates a copy of the repository that belongs to your GitHub account. As an example, this is one of the developer's forks; they are free to make any changes to their repository, having no effect on the OpenRA repository. At a later point they may ask to create a pull request to merge their changes to the OpenRA repository. This does not put any code on your machine, so the next step is to start using git.
To fork, open the OpenRA repo page and press the fork button () on the top right of the screen.
Git is a source control tool used by many projects (including OpenRA), while GitHub is a web interface for a Git repository. Git will allow you to manage your copy of the OpenRA source code. This guide uses the Git command-line, for beginners it can be difficult, but these commands are consistent among all Git clients.
In the guide whenever you see
$YOU, replace it with your GitHub username.
For GitHub to know who you are when using Git, type these two commands:
git config --global user.name $YOU git config --global user.email email@example.com
TIP: You may wish to use your real name instead of your GitHub username for the
To get the source code on your machine and change to that directory, type these two commands:
git clone https://github.com/$YOU/OpenRA.git cd OpenRA
TIP: the code will be in the current directory +
Add a remote for the main OpenRA repository, named
upstream. Type this command:
git remote add upstream https://github.com/OpenRA/OpenRA.git
Another remote named
origin was added when you performed the clone, which points to your own repository.
TIP: Git can interact with other GitHub repositories by providing either a path to the repository, or the remote name. The
upstreamremote that was just set up points to the
http://github.com/OpenRA/OpenRA.gitpath. Both could be used interchangeably. You can also add remotes for other developers' repositories as well if desired.
TIP: To see a list of configured remotes run
git remote -v.
upstreamare common conventions for remote names, referring to the origin of code (where you cloned from), and the official OpenRA repository. You may add more remotes later with different names.
Ensure your copy of Git is up to date with all the various commits / branches / tags that exist in the OpenRA repository on GitHub by entering this command:
git fetch --all
TIP: At this point in time your code is probably up to date regardless. For future fetches, you should only need to use
git fetch upstream.
To make sure everything is good, type this command:
You should see
On branch bleed and
Your branch is up-to-date with origin/bleed.
bleedbranch will be identical to the OpenRA repository's
bleedbranch at this time.
The OpenRA repository has three branches:
- Master (contains code and tags for releases).
- Next (contains code and tags for playtests).
- Bleed (contains code at the latest state).
Keeping up to date (rebasing)
Your copy of the code will eventually fall behind and no longer be the most recent. If you are curious if your
bleed branch has fallen behind, type
If you're up to date, you'll see:
Your branch is up-to-date with 'upstream/bleed'.
If you're behind, you'll see:
Your branch is behind 'upstream/bleed' by # commits, and can be fast-forwarded.
We recommend that you perform a
git rebase by executing these two commands:
git fetch upstream git rebase upstream/bleed
TIP: You may run into a merge conflict, which means that your committed code has a conflicting change with other code that has changed in
upstream. Unfortunately at this time we do not have documentation on how to solve merge conflicts, but the internet does - feel free to ask via IRC for help.
Please see the Compiling wiki page for how to build.
Creating a commit
Work can be done entirely on your
bleed branch, but it's advised to switch to different branches when working on different features or bugfixes. Developers will have many branches (and don't follow the master/next/bleed structure in the OpenRA repository). These branches can be explored by visiting a developer's GitHub OpenRA repository and clicking the "Branches" drop down list.
Here's a way to make sure you create a branch based off of the latest OpenRA repository
bleed, and change to it:
git fetch upstream git checkout -b myfeature upstream/bleed
This will create the branch
myfeature, which will be based on
upstream/bleed, and check it out.
TIP: This branch won't be visible on GitHub until you push it (mentioned later on). Also, do not use an Issue number in your branch name. Github will spam that issue with an update every time you push a fix to the branch.
- Your branch is up to date,
- And you've made the code changes you want,
- And (if you intend to submit a pull request) your code follows the OpenRA coding standards,
You can prepare a commit. Type
git status to see the staged changes you have. It will mention there are files not staged for a commit. There's two ways to do the commit:
- If all of the files modified need to be committed, you can type
git commit -a -m "Added brand new feature"
- If you want to only commit certain files, you can type commands similar to this:
git add file1 git add file2 git commit -m "Added brand new feature"
git rm file1removes a file from staging.
Pushing to GitHub
Once your patch has been committed to your local OpenRA repository, it still isn't visible on your GitHub repository. To do this type the command:
git push origin myfeature
You should see a message like
[new branch] myfeature -> myfeature. You can see this is successful by navigating to your GitHub page and clicking the Branches drop down list.
You can also push your local bleed branch to your GitHub repository in the same way:
git push origin bleed
You can save some work (both for us, and for yourself) by making sure that your pull request passes the following checklist before creating your pull request:
- Have you considered how your changes integrate with the rest of the game? You may be asked to rethink your approach if it interacts badly with other systems.
- Have you tested all of your changes?
- Do your changes conform to the OpenRA coding standard?
- Does it pass our lint test suite (run via
If so, and you're satisfied with your patch, then feel free to create a pull request.
Creating a Pull Request
There are two ways to create a pull request.
- If you open the OpenRA repository page you should see a button called Compare & pull request that wasn't there before, click this button.
Example pull request by user
- If you open the OpenRA repository page and navigate to the pull requests page and click New Pull Request. If you continue with this method, make sure you click the compare across forks hyperlink:
Example pull request by user
Ensure the base refers to OpenRA's bleed branch, while the head refers to your own branch.
Example pull request by user
Once you've done either 1 or 2 above, you can fill in details about your pull request. The title should briefly describe what your fix is, and the description should give a detailed information about what your patches do. If your pull request fixes an issue, type Fixes (#Issue) or Closes (#Issue) in the description. This tells github to close the issue upon merging.
Example pull request by user
Also worth paying attention to is that the commit history below matches your branch (there aren't any extra commits that shouldn't be there). Sometimes when a pull request is incorrectly set up, you will see several other peoples' commits too.
Once satisfied, click the Create Pull Request button. You will be transported to a page containing your pull request.
What is this "We can't automatically merge these branches" message when creating a pull request?
You are still fine to create the pull request. This happens when your branch is not rebased with the latest copy of OpenRA's
bleed branch. See this section of the guide for an overview of rebase if required, and continue on with the guide.
Pull request process
Here's a snapshot of the pull request queue, to give an example of what might be in there:
Your pull request will have tags associated with it. These tags can only be added by members of the OpenRA repository. Labels are color coded.
- Orange/Red require a change by the user who opened the pull requests
- Green labels require action by a reviewer
Your pull request also requires that it will be reviewed by at least 2 separate reviewers, who will:
- Test your code to ensure it works
- Review your code to ensure it follows OpenRA's standards
Updating a Pull Request
You may be asked to update your pull request if:
- Your code doesn't compile
- Code style violations were found during review
- Bugs were found during testing
- Code has a design problem
- Fixup commits need to be squashed
- Your branch is no longer up to date with OpenRA's
1. Code does not compile - OpenRA's repository is set up to automatically compile pull requests, using a utility named Travis CI. This ensures that your code actually builds, and it passes automated tests that are put in place.
You can tell the build has failed if you see this on your pull request:
If this occurs, a reviewer may leave a message on your pull request about what the problem was. If you are interested in finding out for yourself, you can attempt to read the Travis CI build log, ask someone, or try building the code for yourself again.
2. Code style violations - Review the coding standard. It may not follow your personal standard, but this is common among any established code base.
3. Bugs found - Feel free to ask questions for help if you're unsure how to fix a bug that is found by a reviewer.
4. Code design problem - Your patch may work but it might not be in the best interest of the engine in the long run. You may be asked to change your code to work a bit differently. Work with the reviewer on the pull request (or even better in IRC) if you have questions.
5. Fixup commits need to be squashed - A fixup is a change that would normally fit under an existing commit. These new commits need to be squashed into the commit they would natrually fit under.
6. Rebase required - You can be asked to rebase your changes. If a rebase is required, on your pull request page you will see:
If you type these git commands (while on your branch):
git fetch upstream git rebase upstream/bleed git push origin +myfeature
+means to force a push to the
myfeaturebranch, it will overwrite your branch history, be careful!
TIP: A force push is only required if you are overriding an existing branch (usually done when squashing commits).
myfeaturerefers to your branch name.
You should see Git pull down the latest changes, but then also add
Applying: messages to your commits. This is applying your commit messages after pulling down the latest copy of
Visit your pull request page again -- if you have rebased successfully, you will see: