Working with the Umbraco Source

So your ready to contribute? or you just want to get your hands on the source code so you can debug that annoyance that has been hanging around for a while? You've come to the right place.  The following information will guide you through downloading (checking out) the code, how to fork the code, and if you want to contribute your change back, how to submit a pull request for approval.

Checking out the source code

The source code for Umbraco is held at GitHub which is the home of many open source projects.  We have chosen to work with Git as our flavour of source control.

You could simply download the source by visiting our page on Githuib at the following address https://github.com/umbraco/Umbraco-CMS and clicking the "ZIP".  However we do not advise this as it will make it difficult to keep your local copy of the Umbraco source up to date.

The best way to get a copy of the source is to 'clone' a copy using a Git client. There are many Git clients available that can be used with GitHub. There's a "Clone in Windows" or "Clone in Mac" button right there on the GitHub page that will lead you through the installation of the GitHub client and help you clone the source code.

For more information please see the GitHub for Windows or GitHub for Mac pages.

Forking the project

So you've decided that you want to try out something awesome or fix that annoying bug.  The best way to approach this if you are not part of the Core Team who have commit rights to the main repository is to first create a Fork of the project.  This basically creates a copy of the source code into another repository that you can check code in and out of without affecting the main master repository.  

It is important to note that generally you would need one branch per pull request. However if the bug or annoyance that you are repairing is highly related to another issue it may be acceptable fix those issues in a single branch. In those cases its a good idea to contact the Core Team to discuss your changes to ensure your approach is accepted.

GitHub has awesome documentation on creating a fork of the repository.

You should be able to check out and work with your Forked repository like it was your own building and breaking (hopefully not) to your heart's content without affecting the main repository.

Submitting a Pull Request

Once your satisfied with what you have done and your code meets all the guidelines outlined in the Guidelines for core contribution page you can submit a pull request for consideration for inclusion in the Core.  Please note that a pull request should generally only address one issue unless the request covers more than one highly related issues. If in doubt contact the Core Team.

More information about submitting a pull request can be found on GitHub's help pages.

A member of the core team will assess your pull request and provide you with feedback and ultimately acceptance or rejection of the pull request.

If you get rejected they will generally tell you why so if applicable you can fix it.

When you're working on multiple issues at the same time, the suggested flow is as follows:

* The reason: when we don't get to your pull request in time, the branch you made it for will be deleted and that automatically closes your pull request. You can retarget the pull request but it's a bit more manual work, so using dev-v7 is preferred. 

Retargetting your pull request

If your pull request does get closed because the branch you submitted it for gets deleted (see comment above), here's what you can do:

Syncing your fork with the original repository

We strongly recommend you sync with our repository before you submit your pull request. That way, you can fix any potential merge conflicts and make our lives a little bit easier.

Also, if you've submitted a pull request three weeks ago and want to work on something new, you'll want to get the latest code to build against of course.

To sync your fork with this original one, you'll have to add the upstream url. You only need to do this once:

git remote add upstream git://github.com/umbraco/Umbraco-CMS.git

And then each time you want to get our changes:

git fetch upstream
git rebase upstream/dev-v7

Of course if you want to get the updates of a specific branch, you use that branch instead of "dev-v7". For example:

git fetch upstream
git rebase upstream/7.0.0

More info on how this works: http://robots.thoughtbot.com/post/5133345960/keeping-a-git-fork-updated

Coding standards and guidelines

It is important to note that if your code does not meet the standards set out in the guidelines that your pull request will most likely be rejected so its important that you adhere to them as closely as possible.