Whether you're a seasoned developer, a creative designer, or a passionate user, there are countless ways to contribute to the Umbraco project. From coding and bug reporting to sharing your insights and creating tutorials, your input helps us shape a better experience for everyone.

Why contribute to an open-source project?

There are plenty of great reasons to get involved in open-source projects, and when it comes to Umbraco, the benefits are even greater! Here’s why you should consider contributing:

• Expand your skill set: Gain valuable experience and learn new technologies.

• Boost your career: Enhance your public résumé.

• Build your network: Connect with fellow Umbraco enthusiasts and team members.

• Learn and unlearn: Discover new insights and challenge your existing knowledge.

• Make an impact: Your contributions can help thousands of users. Imagine saying, "I helped fix that bug!" 😎

• Impact the planet: We plant a tree for each accepted contribution 🌳

• Support the community: Help the hundreds of thousands of Umbraco users benefit from your efforts.

• Give back: Contribute to the software you love or tackle that feature you've always wished was different!

So, let’s get those contribution hats on!

Where to contribute

Discover where you can make an impact and start contributing.

Documentation

First off, there's a lot of documentation, and it's not always easy to keep it updated or know if we covered all the details you need to know to follow them. We would love your help to verify the documentation. That is, to follow the docs to the letter and see if you’re successful or missing anything.

Find detailed instructions on how to contribute to the docs directly on the documentation site. Here, we have outlined the steps involved with testing and checking the articles against our style guide. In the same article, you can also learn much more about the rules we’re checking the docs against.

Head on over to the contributing guide for Documentation for the full details.

Umbraco CMS

There are plenty of up-for-grabs issues to look at - a great starting point if you’re not quite sure where to start.

We're also happy for you to work on translations or other problems you might know of that are not on the issue tracker yet.

Head on over to the contributing guide for Umbraco-CMS for the full details.

UI Library

The UI library contains all the UI elements for the backoffice. These are self-contained components that can be used in any project that needs a UI.

Head on over to the contributing guide for Umbraco.UI for the full details.

We have general contribution guidelines available for Umbraco-CMS, the backoffice project, the UI library and documentation.

Specificially for Hacktoberfest, we have a lot more things you can get involved in!

Umbraco 15 release candidate testing

One of our main focus areas for 2024 is to deeply test out the major new features of Umbraco v15. The release candidate for the upcoming Umbraco v15 is available now and we encourage you to test the main new features, namely:

• The new rich text editor (RTE)

  • Migrating existing RTEs to the new RTE datatype

  • Working with the new RTE

  • Extending the new RTE

• Lazy-loaded content, which is replacing the main caching mechanism

  • Upgrading existing sites and making sure everything still works on the frontend

  • If you have any custom routing or controllers in place, do they still work as expected

  • Try out the new ISeedKeyProvider, IDocumentServices and IDistributedCache

• Block-level variants

  • Making sure all of your existing blocks work after an upgrade

  • If you have a very large block-based site, it is interesting to see if the upgrade doesn't take too long

  • Add variants to your existing or new blocks and start using them: edit, save, publish, etc

Once you have done a round of thorough testing, please make sure to report any issues on the tracker as usual.

Making it count for Hacktoberfest

We really appreciate your help in testing this release. Please make sure to describe to us in a bit of detail what you've tried, let us know a bit about the scale of project you're testing on, etc.

If everything "just" worked (🤞) then describe that as well! Let us know exactly what you focused on that worked well.

You can do this by heading to the HacktoberfestActivityLog repository and adding your name to the list in the "Low code/no code" section.

An example of a participation entry is:

- 2024-10-04 - Paula Philips - Umbraco 15 Release Candidate testing - Details in the PR description

In the description of the pull request to get your name added, please put your test results as described above and link to any issues you've created if things didn't work as expected.

Packages

Packages are back on the menu - and yes, they also count as a contribution to Umbraco!

Here are some specific details on this:

• Only contributions made to open-source Umbraco packages added to the Hacktoberfest Package repo list counts

• Follow the contribution guidelines provided by the package creator

• Look for the "help wanted" label on the issue tracker associated with the package you want to help out with

• Read much more about how this works, and guidelines on adding your own package repo to the list on the Umbraco Packages Hacktoberfest homepage.

Please note: Package contributions eligibility for swag differ slightly from those used for all contributions. Read more on the Packages Hacktoberfest guidelines to learn more about how a contribution is marked as "swag-eligible".

Creating a brand-new package

Publishing a brand new package to the Umbraco Marketplace will also count towards both DigitalOcean's and Umbraco's Hacktoberfest contributions ⭐🤩

Packages for Umbraco 14 and up are eligible by default, even if the equivalent package already exists for older Umbraco versions.

Check out Lee Kelleher’s list of potential new package ideas!

Low-code / no-code contributions

Back, by popular demand, we will also be rewarding contributions that are either low-code and more importantly: no-code!

Eligible contributions according to the Hacktoberfest guidelines include:

• Verifying documentation

• Copy editing

• User experience testing

• Talks or presentations

• Blog posts

• Podcasts

• Case studies

• Organizing Hacktoberfest events

We have set up a special GitHub repository for you to record your contributions that are not a pull request.

In order to record your journey of verifying documentation (like related blog post(s) in October, events organized), please edit the README.md file and add your activity at the end in the recommended format and submit that as a pull request. We’ll take it from there!

Sponsor an Umbraco-related GitHub repository

To appreciate people who maintain open-source projects for the Umbraco ecosystem, an easy way to help contribute is to give them some money! We’d suggest you have a look at your favorite packages and see if their repo/maintainer is accepting sponsorship.

We suggest you scroll through the list of topics on GitHub, filtered by Umbraco, and see if your favorite packages/authors are open to sponsorship. Look for the heart icon.

If you're in doubt if your chosen sponsorship would count, then feel free to first create an issue on the Hacktoberfest Activity Log repository, or ask on Discord in the #contributing channel.

Umbraco HQ sponsors 4 different projects at the moment, at $100 per month. These are excellent projects that could always use more sponsorships, but make sure to also consider other repositories, there are many great ones out there!

And the good news is: yes, you will be able to earn Umbraco swag, proportionate to your sponsorship amount.

How we judge a Hacktoberfest-eligible contribution

We use the Hacktoberfest participation rules to qualify, so any contributions that do not follow these standards will also not count towards Umbraco swag. These rules are to ensure we get quality contributions and that the right efforts get rewarded 🙌

If you’re contributing to one of the open-source Umbraco Packages, please check the Packages Hacktoberfest guidelines to learn more about how a contribution is marked as "swag-eligible".

Any questions?

In order to help you succeed we at HQ are trying to be available as much as possible during the month of October on Discord in the #contributing channel.

Whether you need some inspiration, guidance, help getting things to build, and so on - we’re there to support and guide you, together with the Core Collaborators team.

So come join us and the other 1500+ people already on the Umbraco Discord server!

Happy Hacktoberfest! 🎃

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.

• Adding new dependencies 🔒 - if you are in need of adding a new dependency for Umbraco CMS to take on, this should be discussed first; dependencies need to be updated and can lead to unwanted security issues, so we only take on what is absolutely necessary.

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?

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.

👍🎉 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.

Getting Started

We have a guide on and more detailed guides at the end of this article.

The following steps are a quick-start guide:

1. Fork

   Create a fork of

1. 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.

1. Switch to the correct branch Switch to the main branch

2. 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.

1. 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 main, create a new branch first.

2. Change

   Make your changes, experiment, have fun, explore and learn, and don't be afraid. We welcome all contributions and will .

3. Commit and push

   Done? Yay! 🎉

   Remember to commit to your new temp branch, and don't commit to main. Then you can push the changes up to your fork on GitHub.

4. 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? .

Further contribution guides

Code of Conduct

This project and everyone participating in it, is governed by the [our Code of Conduct][code of conduct].

What can I contribute?

We categorise pull requests (PRs) into two categories:

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.

Making larger changes

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.

Pull request or package?

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.

Ownership and copyright

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.

When contributing to the Umbraco documentation, it is useful to know how to structure directories, files, and images.

In this article, you'll get an overview of the file structure and learn about the naming conventions used for elements in the structure.

File names

How files, directories, and images are named is important for consistency, but also for ensuring continuous compatibility with GitBook, where the Documentation sites are hosted.

• All file and directory names must use lowercase.

  • Exception: Name all parent articles README.md, and name the surrounding directory using the title of the README.md file.

• Use hyphens (-) instead of spaces.

• Use the title of the article when naming the associated file.

• Give images descriptive names matching the content associated with them.

File structure

The overall structure of the Umbraco documentation is divided by version and product. Each Umbraco version has its own directory, and in those, each product has its own directories with articles and images.

Diving one step deeper, each individual topic is contained in its own directory.

Each directory must have a README.md file which will act as a landing page for that directory and a parent page to all other articles added within.

When images are used, they must be in an images directory next to the .md file referencing them using relative paths.

• /topic (directory)

  • README.md (landing page/parent article)

  • another-article.md

  • /images (directory)

    • images.png

  • /subtopic (directory)

    • README.md (landing page/parent article)

    • article.md

    • another-article.md

    • /images (directory)

Documentation Navigation

Independent of how the files are structured in the directories, it is the SUMMARY.md file that ultimately determines how the documentation navigation is displayed.

Each product directory has a SUMMARY.md file wherein all articles related to that product are listed.

It is possible to add groups to separate the article into sections. This is done using two # symbols followed by the section name: ## Fundamentals .

Structural Changes

These changes include moving an article to a different section, renaming or deleting an article as well as adding a new article.

When either of the actions above occurs, it needs to be tracked in two files: .gitbook.yaml and SUMMARY.md.

Moving an article

When an article is moved to a different section/directory, follow these steps:

1. Update the relative path to the file in the closest SUMMARY.md file.

2. Move the article link in the SUMMARY.md file to the correct section.

3. Add a redirect to the redirects section of the closest .gitbook.yaml file.

   1. Example: relative/path/to/current/location: relative/path/to/new/location.md

Renaming an article

When an article is renamed, follow these steps to track the changes:

1. Update the Title and the relative path to the file in the closest SUMMARY.md file.

2. Add a redirect to the redirects section of the closest .gitbook.yaml file.

   1. Example: path/to/current-name: path/to/new-name.md

Deleting an article

When an article is deleted from the documentation, follow these steps to avoid broken links:

1. Remove the file from the closest SUMMARY.md file.

2. Add a redirect to the redirects section of the closest .gitbook.yaml file.

   1. Point to either the article's replacement or to the parent article.

   2. Example: path/to/article: path/to/new-article-or-parent.md

Adding a new article

When a new article is added, it must also be added to the SUMMARY.md file to show up in the published documentation:

1. Add the article to the SUMMARY.md file like this:

   • Example: * [Article Title](path/to/article.md)

There are 2 common scenarios where you might want to add a new article to the Umbraco Documentation:

1. You are adding new material to the documentation site.

   1. This includes topics or tutorials not previously covered..

2. You are updating an existing article for an Upcoming major version of a product.

Add New Material to the Documentation

When you are adding a brand new article to the Umbraco Documentation, there are a few questions that we recommend asking yourself before getting started:

The steps to create, write, and add a new article to the Umbraco Documentation are outlined below:

1. Access the UmbracoDocs GitHub repository.

2. Fork the repository.

3. Clone your fork to your local machine.

4. Create a new branch using the following naming convention: productname/topic

   • Branch name example: cms/new-content-app-tutorial

5. Locate the section or folder in the existing structure where your article fits.

6. Create a new .md file and name it using the title you will give the article.

   • The file name needs to be in small caps and use hyphens instead of spaces.

   • File name example: statistics-content-app-tutorial.md.

7. Write the article following:

   1. Umbraco Style Guide

   2. Markdown Conventions.

8. Add your new article to the SUMMARY.md file so it appears in the documentation navigation.

9. Commit and push your changes to your forked repository.

10. Submit a PR to the official UmbracoDocs repository.

Update an Article for an Upcoming Major Version

The documentation is versioned using directories in the root of the repository. The major Umbraco CMS version number is used to name the directories, and you will find documentation for each versioned Umbraco product within them.

The following sections of the Umbraco Documentation follow the versioning strategy:

• Umbraco CMS

• Umbraco Forms

• Umbraco Deploy

• Umbraco Workflow

• Umbraco Commerce

• Umbraco UI Builder

• Umbraco Engage

Once the RC is released, you can find the associated documentation using the version drop-down on the Documentation site.

Update an article for the upcoming release

1. Access the UmbracoDocs GitHub repository.

2. Fork the repository.

3. Clone your fork to your local machine.

4. Create a new branch using the following naming convention: productnameXX/topic

   • Branch name example: cms15/configuration

5. Locate the article you need to make changes to.

6. Make the necessary changes to the article.

7. Add and commit the changes.

8. Push the branch to your forked repository.

9. Submit a PR to the official UmbracoDocs repository.

Finding your first issue: Up for grabs

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.

Making your changes

Great question! The short version goes like this:

1. Fork

   Create a fork of Umbraco-CMS on GitHub
2. Clone

   When GitHub has created your fork, you can clone it in your favorite Git tool
3. Switch to the correct branch

   Switch to the main branch

4. Build

   Build your fork of Umbraco locally as described in the build documentation: you can debug with Visual Studio Code or with Visual Studio.

5. 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 main, create a new branch first.

6. Change

   Make your changes, experiment, have fun, explore and learn, and don't be afraid. We welcome all contributions and will happily give feedback.

7. Commit and push

   Done? Yay! 🎉

   Remember to commit to your new temp branch, and don't commit to main. 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:

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

Then when you want to get the changes from the main repository:

git fetch upstream
git rebase upstream/main

In this command we're syncing with the main branch, but you can 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.

The Umbraco Documentation is written in Markdown.

In this article, you can learn how Markdown is used for adding different elements to the articles.

Headings

To create a heading, add between one to four # symbols before your heading text. The number of # you use will determine the hierarchy level and size of the heading.

# Article Title
## Heading 1
### Heading 2
#### Heading 3

When two or more headings are used in an article, they will be used to generate a table of contents on the right side of the article. Heading 3 will not be shown in the table of contents.

Styling text

Links

In the following, you will find a few examples of different links.

External links

Include either the complete URL using the following syntax:

[yahoo something](https://yahoo.com/something)

All external links open in a new browser tab.

Internal links

When linking between pages in the documentation, use relative paths.

Link to an article in the same directory as the current article:

[Article Title](article.md)

Link to an article in a different directory than the current article:

[Article Title](../../reference/article.md)

Page Links

It is possible to add a page link that spans the entire width of the page. This is generally used for linking to a new subject related to the article at hand.

The following is a page link that links to the "Submit Feedback" article:

{% content-ref url="issues.md" %}

[Article Title](issues.md)

{% endcontent-ref %}

Link Text

Use the title of the article that is linked to as the link text. This is done to tell the reader what they will find on the other end.

Do not use "here" or "link" as the link text, as this provides no information about the destination.

⛔ Learn more about Document Types here.

✅ Learn more about Document Types in the Defining Content article.

Images

Images used in documentation articles must always be added to the repository as well. Learn more about where to add the images in the File Names and Structure article.

Use relative paths when referencing images in an article.

Use descriptive alt text and captions to enhance accessibility and Search Engine Optimization (SEO) benefits.

// Block with Caption

![This is a sample Caption](images/sample.png)

// Block with Alt text

<figure><img src="images/sample.png" alt="This is a sample Alt text"></figure>

// Block with Caption and Alt text

<figure>
  <img src="images/sample.png" alt="This is a sample Alt text">
  <figcaption>
    <p>This is a sample Caption</p>
  </figcaption>
</figure>

Best practices when working with images

• Use clear and relevant filenames. Example: dashboard-view.png instead of image1.png.

• Avoid placing large amounts of text in images. If text is required, provide it in the article instead.

• Use SVG format for diagrams and icons where possible to ensure scalability.

Notes and Warnings

Four types of hints can be added to our documentation: info, success, warning, and danger.

Learn more about how to use hints in the GitBook Docs.

Advanced Blocks

It is possible to add more advanced elements such as Expandables and Tabs. These are created using specific GitBook syntax

Learn more about how to work with these elements on the official GitBook documentation:

• Expandables

• Tabs

You can contribute to the Umbraco Documentation by submitting a Pull Request (PR). A PR is a way to suggest changes to an open-source project, such as fixing errors, improving readability, or adding new content.

There are two ways to create a PR:

1. Edit a file directly on GitHub.

2. Create a fork of the GitHub repository.

Option 1: Creating a PR directly on GitHub

You can submit a PR directly from our . You can also use the button on the right side of every article title. This allows you to jump straight into the file on GitHub and suggest your changes.

Following the approach is recommended for changes such as:

• Fixing typos or grammar mistakes.

• Changes that are confined to a single article.

• Updating code snippets.

1. Navigate to the article you want to edit.

2. Select "Edit on GitHub" from the right side of the article.

3. Select the 🖊️ icon to start editing the article.

4. Make the changes.

5. Add a commit message describing what you changed.

6. Select Propose changes.

7. Fill in the required information in the PR description.

8. Select Create pull request to submit the PR.

Option 2: Creating a PR through a Fork

The second option to submit a PR is by using a fork of the Umbraco Documentation repository. This method requires more initial setup but lets you reuse your fork for future contributions.

Following the approach is recommended for changes such as:

• Writing new articles or guides.

• Adding updates that affect multiple articles.

• Applying an update that needs to be added to multiple versions.

There are a lot of great tutorials available online on .

Step 1: Creating a Fork

1. Ensure Git is installed on your machine.

2. Go to the .

3. Select Fork in the top-right corner to create a personal copy of the repository.

Once the fork is created:

1. Clone your fork to your local machine.

2. Make your changes in a local branch.

3. If you add a new article, update the SUMMARY.md file to include it in the documentation navigation.

4. Sync your changes back to your fork.

To sync via command line:

• Set the original repository (UmbracoDocs) as an upstream to sync from.

• Fetch the updates.

• Update your own fork.

To sync via GitHub:

• Use the Sync fork option when your fork is behind the original repository.

Step 2: Creating a PR

Once you have made changes and are happy with the result, you can create a PR.

1. Navigate to the Code section of your fork.

2. Select Contribute > Open pull request.

1. Add a title and description explaining your changes.

2. Select Create pull request to submit a PR to the original repository.

Step 3: The Review Process

Your PR will be reviewed by the documentation team at Umbraco HQ.

Review times can vary based on the size and complexity of the contribution—from a few minutes to several weeks.

Contributing to Umbraco UI

Please review this document to help to streamline the process and save everyone's precious time.

This repo uses nodejs, so you should install nodejs as the package manager. See installation guide.

Guidelines for contributions that we welcome

Not all changes are wanted, so on occasion we might close a PR without merging it. We will give you feedback why we can't accept your changes and we'll be nice about it, thanking you for spending your valuable time.

Remember, it is always worth working on an issue from the Up-for-grabs list or even asking for some feedback before you send us a PR. This way, your PR will not be closed as unwanted.

Feature requests or ideas should be submitted as a discussion first and may then later be converted into an issue.

Ownership and copyright

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.UI and 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.

What can I start with?

Unsure where to begin contributing to the Umbraco UI library? You can start by looking through these Up-for-grabs issues

Pull Requests (PRs)

We welcome all contributions. There are many ways you can help us. This is few of those ways:

Before you submit a new PR, make sure you run npm run test. PR must pass all the tests before it can get merged.

Reviewing PRs

As a PR submitter, you should reference the issue if there is one, include a short description of what you contributed and, if it is a code change, instructions for how to manually test out the change.

Please follow the pull request template you get provided when creating a pull request.

NOTE: Although the latest released version of Umbraco UI corresponds to the main branch, then development happens in the dev branch. If you submit a PR, branch off dev and target your PR to dev.

Development Guide

The UI Library components are web components built with Lit and Typescript. Lit is a light-weight base class that makes development of web components easier and handles all the necessary things, attaching shadow root, reactivity, attribute reflection etc. We strongly encourage you to take a look at Lit documentation before starting development.

Using Typescript is mandatory when contributing to this repository, although it is not necessary to use it when consuming the components.

How to get started

1. Make sure you have the recommended version of node.js and npm installed

   1. Currently we use node.js v16 and npm v8

2. Run npm install

3. Run npm run storybook to start the storybook server, which we also use for development

New component

You can create a new component and that way contribute to the UI library. But before you do that, go to the packages folder and check if it's not already there. You can also look at the Components list for an inspiration, where you can check what component is in what stage.

Package anatomy

Each component is a separate npm package and has a fixed file structure that looks as follows:

• packages

  • new-component-name

    • lib

      • index.ts

      • new-component-name.element.ts

      • new-component-name.test.ts

      • new-component-name.story.ts

    • package.json

    • README.md

    • rollup.config.js

    • tsconfig.json

To scaffold these files run:

npm run new-package
npm i

tsconfig.json file is generated automatically when the postinstall script runs.

Properties and attributes

Reactive properties are what creates the component's public api API. They all have corresponding attribute, through which the property can be initialized when the custom element gets instantiated and connected to the DOM. By default the property is not reflected to the attribute, meaning if property value changes the attribute in the markup will keep its initial value, but it will stay observed - changing its value wil change the property. Attributes can also be reflected, and used for styling purposes for example.

Each property you create should be documented with a jsdoc snippet. You can see an example of a property below.

  /**
   * Disables the button, changes the looks of it and prevents if from emitting the click event
   * @type {boolean}
   * @attr
   * @default false
   */
  @property({ type: Boolean, reflect: true })
  disabled = false;

Best practices for contributing to this library

• Properties should only use attr-reflection for styling - don’t map component-state to classes - use attr-reflection!

• New dependencies can only be added by HQ-team and only after scrutinizing debate (to keep size down)

• Components versions can only be bumped by HQ-team

• Components can’t assume Umbraco context

• Elements shouldn’t depend on TagNames - their own or children - instead use :host or this and use classes/id’s for selection

• Elements always use a shadow-root (shadowDOM - for encapsulation)

• Styles should have as simple rules as possible

• UI-events should be unique types that extend from our UUIEvent (see uui-base package) (for typing reasons)

• When applicable, elements should follow aria accessibility patterns

Before a new element can me merged

• Element name must be prefixed with “UUI-”.

• Element must have tests and pass them.

• Element must pass basic Accessibility tests.

• Element must have a storybook setup.

• Source-code must follow the ES-lint rules.

Have A Question?

A feature suggestion? Or maybe you think we could do something in other way? Start by filing an issue.

Are you sure?

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 ?

• 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 and start using Umbraco CMS as intended.

Getting Started

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.

Latest version

• If you want to get the latest changes from the client repository, run git submodule update again which will pull the latest main branch.

Debugging source locally

Did you read ?

If you want to run a build without debugging, see below. This runs the build in the same way it is run on our build servers.

Debugging with VS Code

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 .

The caching for the back office has been described as 'aggressive' so we often find it's best when making back office changes to 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 to ease your debugging.

Debugging with Visual Studio

In order to build the Umbraco source code locally with Visual Studio, first make sure you have the following installed.

• ( 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 .

The caching for the back office has been described as 'aggressive' so we often find it's best when making back office changes to 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 to ease your debugging.

Building from source

Did you read ?

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.

Cleaning up

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:

• git

• git

Azure DevOps

Umbraco uses Azure DevOps for continuous integration, nightly builds and release builds. The Umbraco CMS project on DevOps ..

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.

Quirks

Git Quirks

Git might have issues dealing with long file paths during build. You may want/need to enable core.longpaths support (see for details).

Gulp Quirks

You may need to run the following commands to set up gulp properly:

The articles in the Umbraco Documentation can, in most cases, benefit from relevant code samples to support the written text.

This article provides guidelines for formatting and using code samples in the Umbraco Documentation.. You will find definitions and examples of the most commonly used types of code samples.

Example

@if (Model.ColorTheme != null)
{
    var value = Model.ColorTheme;
    <p>@value</p>
}

Markdown

{% code caption="HomePageTemplate.cshtml %}

```csharp
@if (Model.HasValue("colorTheme"))
{
    var value = Model.Value("colorTheme");
    <p>@value</p>
}
```

{% endcode %}

Good practices

To ensure quality and consistent code samples, follow these best practices when adding code snippets:

• Define the context

• Add a Caption (file name)

• Use code comments in longer code snippets

• Use real-life samples

• Add correct syntax highlighting

• Add only complete compilable samples

• Check for syntax errors

• Use File-Scoped Namespaces

• Use line numbers only when relevant

Each guideline is explained in more detail below.

Define the context

Code samples without context, explanations, and instructions can lead to issues when used.

Always add a clear description of what the code sample showcases when adding a snippet to an article. It should be clear where and when the snippet can be used.

Add a Caption (file name)

Inform the reader which file or file type a code snippet should be added to.

Aside from mentioning this in the description of the code snippet, it is also recommended to add the file name as a caption.

If the code snippet is from a .cs file, add fileName.cs as the caption.

Example:

Markdown example:

{% code caption="ErrorController.cs" %}

```csharp

...
```

{% endcode %}

Use code comments

When adding code samples that contain more than a single feature or method, it is recommended to add inline comments.

By adding inline comments, you avoid having too much text surrounding the code sample. You also help readers understand the code snippet in detail.

Use real-life samples

The documentation often aims to explain complex scenarios and concepts within Umbraco. Code samples can be useful to improve understanding. The code samples should, where possible, be real-life examples.

For example, using variables such as foo and bar can distract from the intent of the example. Aim to use an example that would make sense to add to a production environment.

To keep the code sample as neutral and general as possible, make it a habit to use placeholders for names, methods, and the like.

With Umbraco, there are often more than one way to achieve a result. It depends on context and the skillset of the development team. Providing multiple examples can help prevent readers from mixing techniques in their solution. An example could be providing a Models Builder version and a non-Models Builder version when documenting Templates.

Add correct syntax highlighting

When you add code blocks to an article, make sure to add the correct syntax highlighting. This will "prettify" the code in the sample based on which language is used.

Syntax highlighting makes the code snippet easier to read, as it allows the reader to distinguish between the different code elements.

Example:

Markdown example:

{% code caption="ErrorController.cs" %}

```csharp
using Microsoft.AspNetCore.Mvc;

namespace YourProjectNamespace.Controllers;

...
```

{% endcode %}

If the language used in a snippet isn't supported, use none.

Add only complete compilable samples

A reader of the Umbraco Documentation should be able to grab code samples in the articles and apply them directly to their solution. The code in the sample should compile.

Include any relevant Using statements for namespaces that provide 'extension' methods and key functionality.

Check for syntax errors

When reading any piece of text, it can be frustrating to run into spelling and syntax errors. This also applies to code samples.

Any code that is added to articles in the documentation should be double-checked for syntax errors and typos.

Use File-Scoped Namespaces

The use of file-scoped namespaces improves the readability of the code samples. Use file-scoped namespaces in the examples. Below is an example of how to use file-scoped namespaces:

With File-Scoped Namespace

namespace MyProject;

public class Umbraco
{
}

Without File-Scoped Namespace

namespace MyProject
{
    public class Umbraco
    {
    }
}

Use line numbers only when relevant

It is recommended to use line numbers only when you will be adding text that references specific lines and elements in a larger code snippet.

Example:

Markdown example:

{% code title="UmbracoAppAuthenticatorComposer.cs" lineNumbers="true" %}

```csharp
namespace My.Website;

...
```

{% endcode %}

When to use code samples

Code samples are relevant for most types of articles. Potentially, any topic covered could benefit from a real-life code sample to support the article content.

In most cases, you will want to base an article on a single code sample. If you're describing a flow or feature, you will, however, want to add smaller code snippets to highlight specific points.

Types of samples

The Umbraco Documentation operates with three types of code samples.

Inline code

Use inline code when:

• Referencing methods.

• Using the names of certain code elements.

• Highlighting a certain value.

Example:

Each item is treated as a standard `IPublishedElement` entity, which means you can use all the value converters you are used to using.

The markdown above will output the following:

Smaller code snippets

As part of longer articles or tutorials, use smaller code snippets to highlight what must be implemented.

These snippets can be added between sections anywhere in an article without breaking focus from the main topic. Keep in mind that adding too many snippets in quick succession can confuse the flow of the article.

Example:

@{
    // Perform an null-check on the field with alias 'pageTitle'
    if (Model.HasValue("pageTitle")){
        // Print the value of the field with alias 'pageTitle'
        <p>@(Model.Value("pageTitle"))</p>
    }
}

The Razor snippet above will output the following:

Large code samples

As part of tutorials and longer articles covering a specific workflow, it might make sense to add longer code snippets or even entire files.

It is recommended to add longer code snippets into Expandables using the file name as the title. When adding code snippets into expandables, the reader can expand the code only when they are ready.

It is highly recommended to use line numbers in large code samples. This will make it easier to reference certain parts of the sample in the surrounding text.

To ensure that the documentation is readable and has a similar style throughout, follow the guidelines outlined in this article. A GitHub bot will check PRs for broken rules and advise you on what to change.

Text Formatting

Below you will find a description of each rule the Umbraco Documentation follows.

Avoid Punctuation in Headings

Don't use punctuation in headings and headlines. These should act as titles, and no punctuation is necessary.

For consistency, this rule will give a warning if you end headings with either of these punctuation symbols:

• ?

• :

• .

Avoid Double spacing

To ensure readability and consistency, this rule will warn you if you have more than one space in a row in your text.

Use Lists when Listing more than 2 Items/Steps

There are two types of commonly used lists in the Umbraco documentation: ordered lists and unordered lists.

• Use ordered lists for sequential task steps.

• Use unordered lists for sets of options, notes, criteria, and the like.

• Start lists with capital letters.

  • An exception to this rule would be when listing method names that use camelcase. In this case, highlight the names using in-line code formatting.

Ordered lists

To keep ordered lists short and to the point, follow these guidelines:

• Start each item on the list with the action word.

  • ⛔ The next thing to do, is to navigate to the Content section.

  • ✅ Navigate to the Content section.

• Add a maximum of two actions per list item.

• Keep each list item short and to the point.

  • Add additional information in one or more sub-list items.

Language

Write in the second person

Address the reader directly using "you".

⛔ The user should add the Document Type by clicking the Add button.

✅ You can add the Document Type by clicking…

Use the present tense and active voice

Use the present tense for statements that describe general behavior that's not associated with a particular time.

⛔ The Document Type was added…

✅ The Document Type is added...

Avoid Editorializing

The words in the list below will cause a warning when included in your contribution.

Avoid using the following words, as they are often opinionated. What may be 'easy' for you might not be easy for another user reading the article.

In most cases, these words can be removed entirely, whereas a rephrasing might be necessary in other cases.

• Simple

• Simply

• Just

• Easily

• Actually

Avoid Long sentences

This rule flags any sentence longer than 25 words. Shorter sentences improve clarity and readability.

The rule is added to improve the readability of the documentation. When a sentence is longer than 25 words, the readability is degraded. This is especially true for technical content that is meant to be instructional.

Avoid using "it" or "this" as references

To avoid confusion, don't use "it" or "this" to refer to an action or item referenced at an earlier point. The only exception to this rule is when used within the same sentence.

⛔ This can now be configured.

✅ The Document Type can now be configured.

Terms and Names

Terms (general)

This rule flags any use of discouraged terms in the Umbraco Documentation.

Example: The term blacklist must be avoided and replaced with deny list.

For a full list of terms, please check the style rule.

Umbraco Terms

This rule is added to ensure that Umbraco-specific terms and names are spelled and used consistently throughout the documentation.

The list of Umbraco Terms includes, but is not limited to Umbraco, backoffice, Document Type, and Umbraco Forms.

Acronyms

All first-time uses of an acronym in an article need to be accompanied by a definition of that acronym. If an acronym is not defined on its first use in an article, the checker will give a warning.

Acronyms are defined using either a parenthesis or a colon followed by the definition.

Examples of the use of acronyms:

⛔ Members will only have access to CDN endpoints.

✅ Members will only have access to Content Delivery Network (CDN) endpoints.

⛔ YSOD (.Net error page)

✅ YSOD: Yellow Screen of Death, .NET error page

Names

To ensure that markup languages and other names are capitalized correctly, a rule has been added to check for this.

The rule will ensure that instances of HTML and CSS are always written using only capital letters. It will also check whether JavaScript is written in full.

Brands

In some cases, throughout the documentation, other software providers or brands are referenced. This rule is added to ensure that the most commonly used brand names are spelled and capitalized correctly.

The rule will, as an example, ensure that the names Microsoft and Slack are always capitalized.

Test the documentation yourself

One of the big strengths of Vale is that it is possible for a contributor to run the tests locally before creating a PR. Below are a couple of options on how to test the documentation.

There are different ways to submit feedback on the Umbraco Documentation, whether it's about a single article or the platform as a whole. Your input helps us improve and prioritize what matters most to the community.

This article gives you an overview of the different feedback channels and how to use them.

Submit Feedback on an Article

On the right-hand side of every article, you'll find an option to submit feedback directly related to that article.

Submit a GitHub Issue

The Issue Tracker is a way to keep track of ideas, issues with wrong or outdated documentation, and discussions with contributors.

Here are a few examples of when to create an issue:

• You are looking for a specific piece of information, but can't find it.

• You've found a broken link in one of the articles, but don't know how to fix it.

• An article contains outdated or incorrect information, and you don't have time or knowledge to submit a PR.

• You would like to propose a new section or discuss improvements to existing documentation.

Creating an Issue

1. Go to the Issue Tracker on GitHub.

2. Select New Issue.

1. Fill out the form, answering the questions to explain your suggestion or problem clearly.

2. Submit the issue.

The Umbraco Documentation is presented here on GitBook. The documentation is also available as a GitHub repository and is open-source, just like the Umbraco CMS.

You can contribute to the documentation if something is missing or outdated. A GitHub account and a fork of the UmbracoDocs GitHub repository are required.

How to Get Started

There are many ways in which you can contribute to the Umbraco Documentation. The approach you choose to take depends on what you want to achieve with your contribution.

• Request a quick/minor change to an article by submitting a Pull Request.

• Submit a more extensive update or change by forking the Documentation repository.

• Raise a question, start a discussion, or report an issue on the Issue Tracker.

• Help improve the readability of the documentation by verifying articles against our Style Guide.

Style guide

Consistency and readability are important when writing and reading documentation. When you contribute, follow the style guidelines and rules outlined in the Style Guide.

Markdown and formatting

The Umbraco Documentation is written using the Markdown markup language.

File names and structure

Learn how we structure and name files in the Umbraco documentation.

Writing documentation locally

Use a text editor like Visual Studio Code to make changes to the documentation locally. Although it is possible, it is not recommended to use an Integrated Development Environment (IDE) like Visual Studio for making changes to the documentation on your local machine. This is because the IDE may create files in the project that are not needed for the document changes to be implemented.

Multi-version documentation

Whenever a new version of an Umbraco product is released, the previous way of doing things may change. This means that multiple versions of our documentation must exist.

Versioning is done via the file structure, where all versioned products are located under a folder named by the major version of Umbraco.

For example, version folders such as '10' and '11' contain documentation specific to those product versions.

Umbraco Cloud and Umbraco Heartcore are not documented by version, which is why they are separate from this structure.

Learn more about how versioning is managed in the Documenting multiple versions and products article.

Labels

On both Issues and Pull Requests, labels are used to categorize the requests and submissions.

Here's a quick explanation of the labels (colors):

• Category

  • category/missing-documentation

  • category/umbraco-cloud

  • category/pending-release

• Community

  • community/pr

  • help wanted

• State

  • state/hq-discussion

• Status

  • status/awaiting-feedback

  • status/idea

• Type

  • type/bug

• Internal Review

  • review/docsteam

  • review/developer

Labels are added during the initial review of your pull request or issue.