7 Steps to your first PR in Umbraco


Step 1 Create a fork of the repo

The first step to your contributions is to create a fork of Umbraco repository.  Umbraco hosts the code on Github. So its essential you have a Github account. By forking a repository you are creating a copy of the repo for your own use so that you can make changes, essentially have a play around, without affecting the actual repository. So, to fork Umbraco repository go to https://github.com/umbraco/Umbraco-CMS and click the “Fork” button



Step 2 Clone your repo

Now that you have forked the repo you can clone it locally. So in my case I would go to my own fork of the repo and clone it like you would to any Github repo. For v7 of umbraco the branch you should be using is dev-v7. All your branches must be created off this branch. 

Step 3 Setting an upstream

As much as you have forked the repo it is essential to keep it in sync with the original repo. This can be done by setting an upstream on the cloned repo. You can do it via command line or using your Git client. I shall use Sourcetree for this purpose.

In Sourcetree go to Repository -> Repository Settings and click Add in the dialog. Type in upstream as the Remote name and https://github.com/umbraco/Umbraco-CMS.git .Save the changes. 

You can now pull changes from the original repo dev-v7 branch to your dev-v7 branch.Switch to your dev-v7 branch and click Pull in Sourcetree, change the remote to upstream and select dev-v7 branch and click ok. Usually Sourcetree alerts you by indicating the number of changes to be pulled in by the Pull button. 



You can even push the changes you have pulled from the original repo to your own fork.

Step 4 Setting up the solution

You can now set up the solution locally. There is a very good guide on what you need to do in the Umbraco repo which can be found here

Step 5 Decide what you want to work on

With Umbraco you can create new features or do bug fixes. You can always look at the Umbraco issue tracker and try and work on any of the issues marked community/up for grabs.

If you notice a bug yourself in Umbraco you can create a issue in the issue tracker. Be as clear as you can with the bug report and include any screenshots if you can. The HQ has made a great template for Bug Report which tells you exactly what to do. 




Similarly if you would like to request a new feature you can do that by creating a feature request. There is a detailed template for this too. 


There are more templates and info available , all of which you can see when you use the New Issue button by the issue tracker.

Step 6 Working with the code

Once you have an idea on what you need to work on you can start off by creating a branch for your work. For Umbraco v7 you always need to create a branch off the latest dev-v7 branch. I usually name my branches by the issue number, but you can give yours a meaningful name too if you want. 

It is highly recommended that you go through the guidelines available in the repo. 

An important thing to note is that the back office is an AngularJS app. Any changes you make to the views, css or js(basically, any changes to Umbraco.Web.UI.Client project) requires a gulp task to be run. I usually use my Visual Studio Task Runner Explorer for this. Right-click build and click Run. Once this has completed successfully you can open the application in your browser.  




Usually the above step clears the cache and picks up your changes. Another little setting that can help here is Disabling Cache in your browser developer tools. 



Step 7 Create your Pull Request

Commit and push your changes to the branch after testing. You can now create your first pull request. You can either do it from Github or do it via SourceTree. I usually do it from Sourcetree by right clicking the branch and selecting “Create Pull Request”. This should then take you to Github where you can fill the details about your work.

Pull requests for Umbraco v7 must always be created against dev-v7 branch. As with the bug report, there is a template which says what you need to include. Always put the issue link in place. This makes sure that the issue reflects the information on the PR. Include any steps to reproduce the issue and any screenshots if you can. For eg : what the bug was and how does it look after fixing. 



Now click the button and there you have your first PR to Umbraco! Someone from the HQ or the Pull Request Team should be in touch with you after this testing your changes and advising you on further steps!