Getting Started as a Contributor to our Open-Source Projects
Unity and Open-Source
Last month at Unite, we announced our Open-Source initiative, where we will be opening the source to various components of Unity (along with other helpful tools and samples) in the future. We announced the presence of the Unity Test Tools project at our new home on BitBucket and since then we’ve watched as our community has cloned, made forks, and submitted pull requests (you can see the development of the Test Tools happening in the repository itself and the project’s issue tracker being used as well). Since then we’ve released our Xcode Manipulation API (allowing you to modify and adjust a generated Xcode project) and iOS Native Code samples (giving examples for things like how to integrate Unity with native UI and how to do native video rendering). We’re also gearing up to ship you the source for our new UI shipping in 4.6 (which is currently in open beta) and we’re making plans to open the source to other components as well.
We also announced our Contributor’s Guide that is now part of our user manual. Today, I’d like to go through those steps with you.
The Steps to Contributing
Our repositories are hosted on BitBucket under either Mercurial or Git. If you’ve already contributed to a project on GitHub, the process is the same here. If you’re coming from Perforce or SVN (or some other centralized version control system) and these concepts of ‘forks’ and ‘clones’ and ‘pushing’ and ‘pulling’ are all new to you, we encourage you to follow the steps in the contributor’s guide very closely (since they will guide you along with screenshots every step of the way) and also take advantage of the ‘Further Reading‘ section.
The first thing you need to do is get an account on BitBucket, which is where we are hosting our repositories. This is a very straightforward process (f you’re completely new to BitBucket, but have a GitHub account, feel free to use that same account over at BitBucket, (EDIT: You need to create a BitBucket account first and connect your GitHub (or Google) account to it. From then on, you will be able to login to BitBucket with your GitHub (or Google) account) and if you’re wondering why we are on BitBucket instead of GitHub, please see our FAQ.).
Next, you’ll want to make your way over to our home on BitBucket and find the repository you want to contribute to. Once you’ve done that, you’ll want to fork the repository to your own space. A fork of a a repository is simply a clone of a repository, that lives under your own space where you are free to push your own changes to.
Clone your fork and apply your changes. Unless you love getting down and dirty on the command-line, we recommend SourceTree from Atlassian for interacting with both Mercurial and Git. It will work for you whether you are on Mac or Windows, and whether you are using Mercurial or Git.
Finally, open a pull request from your fork and wait. A Unity Developer will look at your pull request and process it, and if it’s approved, it will be merged into our repository.
In the end, the process looks like this:
What Happens to Pull Requests
When you submit a pull request, generally one of four things can happen:
- The pull request is accepted as-is and is merged in its entirety.
- The pull request is closed as rejected.
- The pull request is not closed as rejected, but the Unity Developer will require that you do some extra work before the change can be merged.
- The pull request is rejected, but the Unity Developer still applies some of the changes from the pull request.
Cases 1 and 2 are straightforward. Case 3 usually means you need to do some cleanup or handle some extra cases. Case 4 will usually happen if the Unity Developer doesn’t think all of the changes apply, but wants to take some of them, or if the history of the changes needs to be cleaned up before they can be applied. In our Unity Test Tools project, we’ve already seen cases of 1, 2, and 4.
In all cases, you’ll be notified of activity on your pull request by mail, so be sure you are set up to receive email notifications from BitBucket.
There You Have It
So, in just a few relatively simple and straightforward steps, you can be helping to improve Unity and its ecosystem, both for yourself and the rest of the community! As I’ve said before, we’re excited to see what you create.