This document covers contributing to the codebase of the CMS but the community site has plenty of inspiration for other ways to get involved.
If you don't feel you'd like to make code changes here, you can visit our documentation repository and use your experience to contribute to making the docs we have, even better.
We also encourage community members to feel free to comment on others' pull requests and issues - the expertise we have is not limited to the Core Collaborators and HQ. So, if you see something on the issue tracker or pull requests you feel you can add to, please don't be shy.
This project and everyone participating in it, is governed by the [our Code of Conduct][code of conduct].
We categorise pull requests (PRs) into two categories:
Small PRs
Bug fixes and small improvements - can be recognized by seeing a small number of changes and possibly a small number of new files.
Large PRs
New features and large refactorings - can be recognized by seeing a large number of changes, plenty of new files, updates to package manager files (NuGet’s packages.config, NPM’s packages.json, etc.).
We’re usually able to handle small PRs pretty quickly. A community volunteer will do the initial review and flag it for Umbraco HQ as “community tested”. If everything looks good, it will be merged pretty quickly [as per the described process][review process].
We would love to follow the same process for larger PRs but this is not always possible due to time limitations and priorities that need to be aligned. We don’t want to put up any barriers, but this document should set the correct expectations.
Not all changes are wanted, so on occasion we might close a PR without merging it but if we do, we will give you feedback why we can't accept your changes. So make sure to talk to us before making large changes, so we can ensure that you don't put all your hard work into something we would not be able to merge.
Please make sure to describe your larger ideas in an issue (bugs) or discussion (new features), it helps to put in mock up screenshots or videos. If the change makes sense for HQ to include in Umbraco CMS we will leave you some feedback on how we’d like to see it being implemented.
If a larger pull request is encouraged by Umbraco HQ, the process will be similar to what is described in the small PRs process above, we strive to feedback within 14 days. Finalizing and merging the PR might take longer though as it will likely need to be picked up by the development team to make sure everything is in order. We’ll keep you posted on the progress.
If you're unsure about whether your changes belong in the core Umbraco CMS or if you should turn your idea into a package instead, make sure to talk to us.
If it doesn’t fit in CMS right now, we will likely encourage you to make it into a package instead. A package is a great way to check out popularity of a feature, learn how people use it, validate good usability and fix bugs. Eventually, a package could "graduate" to be included in the CMS.
It is your responsibility to make sure that you're allowed to share the code you're providing us. For example, you should have permission from your employer or customer to share code.
Similarly, if your contribution is copied or adapted from somewhere else, make sure that the license allows you to reuse that for a contribution to Umbraco-CMS.
If you're not sure, leave a note on your contribution and we will be happy to guide you.
When your contribution has been accepted, it will be MIT licensed from that time onwards.
While most changes are welcome, there are certain types of changes that are discouraged and might get your pull request refused. Of course this will depend heavily on the specific change, but please take the following examples in mind.
Breaking changes (code and/or behavioral) 💥 - sometimes it can be a bit hard to know if a change is breaking or not. Fortunately, if it relates to code, the build will fail and warn you.
Large refactors 🤯 - the larger the refactor, the larger the probability of introducing new bugs/issues.
Changes to obsolete code and/or property editors ✍️
Adding new config options 🦾 - while having more flexibility is (most of the times) better, having too many options can also become overwhelming/confusing, especially if there are other (good/simple) ways to achieve it.
Whitespace changes 🫥 - while some of our files might not follow the formatting/whitespace rules (mostly old ones), changing several of them in one go would cause major merge conflicts with open pull requests or other work in progress. Do feel free to fix these when you are working on another issue/feature and end up "touching" those files!
Adding new extension/helper methods ✋ - keep in mind that more code also means more to maintain, so if a helper is only meaningful for a few, it might not be worth adding it to the core.
While these are only a few examples, it is important to ask yourself these questions before making a pull request:
How many will benefit from this change?
Are there other ways to achieve this? And if so, how do they compare?
How maintainable is the change?
What would be the effort to test it properly?
Do the benefits outweigh the risks?
👍🎉 First off, thanks for taking the time to contribute! 🎉👍
These contribution guidelines are mostly just that - guidelines, not rules. This is what we've found to work best over the years, but if you choose to ignore them, we still love you! 💖 Use your best judgement, and feel free to propose changes to this document in a pull request.
We have a guide on what to consider before you start and more detailed guides at the end of this article.
The following steps are a quick-start guide:
Fork
Create a fork of Umbraco-CMS on GitHub
Clone
When GitHub has created your fork, you can clone it in your favorite Git tool or on the command line with git clone https://github.com/[YourUsername]/Umbraco-CMS.
Switch to the correct branch
Switch to the contrib branch
Build
Build your fork of Umbraco locally as shown in the video below. You can build with any IDE that supports dotnet or the command line.
Branch
Create a new branch now and name it after the issue you're fixing, we usually follow the format: temp/12345. This means it's a temporary branch for the particular issue you're working on, in this case issue number 12345. Don't commit to contrib, create a new branch first.
Change
Make your changes, experiment, have fun, explore and learn, and don't be afraid. We welcome all contributions and will happily give feedback.
Commit and push
Done? Yay! 🎉
Remember to commit to your new temp branch, and don't commit to contrib. Then you can push the changes up to your fork on GitHub.
Create pull request
On GitHub, in your forked repository (https://github.com/[YourUsername]/Umbraco-CMS) you will see a banner saying that you pushed a new branch and a button to make a pull request. Tap the button and follow the instructions.
Want to read further? Creating a pull request and what happens next.
Umbraco HQ will regularly mark newly created issues on the issue tracker with the community/up-for-grabs tag. This means that the proposed changes are wanted in Umbraco but the HQ does not have the time to make them at this time. We encourage anyone to pick them up and help out.
If you do start working on something, make sure to leave a small comment on the issue saying something like: "I'm working on this". That way other people stumbling upon the issue know they don't need to pick it up, someone already has.
Great question! The short version goes like this:
Fork
Create a fork of Umbraco-CMS on GitHub
Clone
When GitHub has created your fork, you can clone it in your favorite Git tool
Switch to the correct branch
Switch to the contrib branch
Build
Build your fork of Umbraco locally as described in the build documentation: you can debug with Visual Studio Code or with Visual Studio.
Branch
Create a new branch now and name it after the issue you're fixing, we usually follow the format: temp-12345. This means it's a temporary branch for the particular issue you're working on, in this case issue number 12345. Don't commit to contrib, create a new branch first.
Change
Make your changes, experiment, have fun, explore and learn, and don't be afraid. We welcome all contributions and will happily give feedback.
Commit and push
Done? Yay! 🎉
Remember to commit to your new temp branch, and don't commit to contrib. Then you can push the changes up to your fork on GitHub.
Keeping your Umbraco fork in sync with the main repository
Once you've already got a fork and cloned your fork locally, you can skip steps 1 and 2 going forward. Just remember to keep your fork up to date before making further changes.
To sync your fork with this original one, you'll have to add the upstream url. You only have to do this once:
Then when you want to get the changes from the main repository:
In this command we're syncing with the contrib branch, but you can of course choose another one if needed.
More information on how this works can be found on the thoughtbot blog.
Style guide
To be honest, we don't like rules very much. We trust you have the best of intentions and we encourage you to create working code. If it doesn't look perfect then we'll happily help clean it up.
That said, the Umbraco development team likes to follow the hints that ReSharper gives us (no problem if you don't have this installed) and we've added a .editorconfig file so that Visual Studio knows what to do with whitespace, line endings, etc.
Questions?
You can get in touch with [the core contributors team][core collabs] in multiple ways; we love open conversations and we are a friendly bunch. No question you have is stupid. Any question you have usually helps out multiple people with the same question. Ask away:
If there's an existing issue on the issue tracker then that's a good place to leave questions and discuss how to start or move forward.
If you want to ask questions on some code you've already written you can create a draft pull request, detailed in a GitHub blog post.
Unsure where to start? Did something not work as expected? Try leaving a note in the "Contributing to Umbraco" forum. The team monitors that one closely, so one of us will be on hand and ready to point you in the right direction.
In order to use Umbraco as a CMS and build your website with it, you should not build it yourself. If you're reading this then you're trying to contribute to Umbraco or you're debugging a complex issue.
Are you about to create a pull request for Umbraco?
Are you trying to get to the bottom of a problem in your existing Umbraco installation?
If the answer is yes, please read on. Otherwise, make sure to head on over to the download page and start using Umbraco CMS as intended.
↖️ You can jump to any section by using the "table of contents" button ( ) above.
To run umbraco, we first need to initialize the client git submodule:
Execute git submodule update --init to get the files into \src\Umbraco.Web.UI.Client folder.
This can be executed in the root folder of your cloned repository.
If you are going to run Umbraco for testing, execute dotnet run inside the \src\Umbraco.Web.UI folder.
If you are going to work on the Backoffice, you can either go to the \src\Umbraco.Web.UI.Client folder and check out a new branch or set it up in your IDE, which will allow you to commit to each repository simultaneously:
Rider: Preferences -> Version Control -> Directory Mappings -> Click the '+' sign
If you get a white page, delete \src\Umbraco.Cms.StaticAssets\wwwroot\umbraco folder and run npm ci && npm run build:for:cms inside the src\Umbraco.Web.UI.Client folder to clear out any leftover files from older versions.
If you want to get the latest changes from the client repository, run git submodule update again which will pull the latest main branch.
Did you read "Are you sure"?
If you want to run a build without debugging, see Building from source below. This runs the build in the same way it is run on our build servers.
In order to build the Umbraco source code locally with Visual Studio Code, first make sure you have the following installed.
npm v7+ (installed with Node.js)
Open the root folder of the repository in Visual Studio Code.
To build the front end you'll need to open the command pallet (Ctrl + Shift + P) and run >Tasks: Run Task followed by Client Watch and then run the Client Build task in the same way.
You can also run the tasks manually on the command line:
If you just want to build the UI Client to Umbraco.Web.UI then instead of running dev, you can do: npm run build.
The login screen is a different frontend build, for that one you can run it as follows:
If you just want to build the Login screen to Umbraco.Web.UI then instead of running dev, you can do: npm run build.
The initial Gulp build might take a long time - don't worry, this will be faster on subsequent runs.
You might run into Gulp quirks.
The caching for the back office has been described as 'aggressive' so we often find it's best when making back office changes to disable caching in the browser (check "Disable cache" on the "Network" tab of developer tools) to help you to see the changes you're making.
To run the C# portion of the project, either hit F5 to begin debugging, or manually using the command line:
The initial C# build might take a _really_** long time (seriously, go and make a cup of coffee!) - but don't worry, this will be faster on subsequent runs.**
When the page eventually loads in your web browser, you can follow the installer to set up a database for debugging. You may also wish to install a starter kit to ease your debugging.
In order to build the Umbraco source code locally with Visual Studio, first make sure you have the following installed.
Visual Studio 2022 v17+ with .NET 7+ (the community edition is free for you to use to contribute to Open Source projects)
npm v7+ (installed with Node.js)
The easiest way to get started is to open umbraco.sln in Visual Studio.
To build the front end, you'll first need to run cd src\Umbraco.Web.UI.Client && npm install in the command line (or cd src\Umbraco.Web.UI.Client; npm install in PowerShell). Then find the Task Runner Explorer (View → Other Windows → Task Runner Explorer) and run the build task under Gulpfile.js. You may need to refresh the Task Runner Explorer before the tasks load.
If you're working on the backoffice, you may wish to run the dev command instead while you're working with it, so changes are copied over to the appropriate directories and you can refresh your browser to view the results of your changes.
The initial Gulp build might take a long time - don't worry, this will be faster on subsequent runs.
You might run into Gulp quirks.
The caching for the back office has been described as 'aggressive' so we often find it's best when making back office changes to disable caching in the browser (check "Disable cache" on the "Network" tab of developer tools) to help you to see the changes you're making.
"The rest" is a C# based codebase, which is mostly ASP.NET Core MVC based. You can make changes, build them in Visual Studio, and hit F5 to see the result.
The initial C# build might take a _really_** long time (seriously, go and make a cup of coffee!) - but don't worry, this will be faster on subsequent runs.**
When the page eventually loads in your web browser, you can follow the installer to set up a database for debugging. You may also wish to install a starter kit to ease your debugging.
Did you read "Are you sure"?
Do note that this is only required if you want to test out your custom changes in a separate site (not the one in the Umbraco.Web.UI), if you just want to test your changes you can run the included test site using: dotnet run from src/Umbraco.Web.UI/
You may want to build a set of NuGet packages with your changes, this can be done using the dotnet pack command.
First enter the root of the project in a command line environment, and then use the following command to build the NuGet packages:
dotnet pack -c Release -o Build.Out
This will restore and build the project using the release configuration, and put all the outputted files in a folder called Build.Out
You can then add these as a local NuGet feed using the following command:
dotnet nuget add source <Path to Build.Out folder> -n MyLocalFeed
This will add a local nuget feed with the name "MyLocalFeed" and you'll now be able to use your custom built NuGet packages.
Once the solution has been used to run a site, one may want to "reset" the solution in order to run a fresh new site again.
The easiest way to do this by deleting the following files and folders:
src/Umbraco.Web.UI/appsettings.json
src/Umbraco.Web.UI/umbraco/Data
You only have to remove the connection strings from the appsettings, but removing the data folder ensures that the sqlite database gets deleted too.
Next time you run a build the appsettings.json file will be re-created in its default state.
This will leave media files and views around, but in most cases, it will be enough.
To perform a more complete clear, you will want to also delete the content of the media, views, scripts... directories.
The following command will force remove all untracked files and directories, whether they are ignored by Git or not. Combined with git reset it can recreate a pristine working directory.
For git documentation see:
Umbraco uses Azure DevOps for continuous integration, nightly builds and release builds. The Umbraco CMS project on DevOps is available for anonymous users..
The produced artifacts are published in a container that can be downloaded from DevOps called "nupkg" which contains all the NuGet packages that got built.
Git might have issues dealing with long file paths during build. You may want/need to enable core.longpaths support (see this page for details).
You may need to run the following commands to set up gulp properly:
