Submit a Pull Request

Learn the two different ways to submit a PR to the Umbraco Documentation.

A Pull Request (PR) is a way of submitting changes to an open-source project like the Umbraco documentation.

Let us say you have found a typing or syntax error in one of the articles on the documentation, and you want to correct it. You can do that with a pull request.

There are two ways to create a pull request:

1. You can either edit a file directly on GitHub, or

2. You can create a fork of the GitHub repository.

In order to create a PR to the Umbraco Documentation it is required that you have a GitHub account.

Option 1: Creating a PR directly on GitHub

GitHub has a functionality that allows you to submit a PR directly from our repository. There is also a button on the right side of every article title, which allows you to jump straight into GitHub to suggest your changes.

Highlighting the Edit on GitHub button.

1. Select "Edit on GitHub" from the right-side of the article you want to suggest changes to.

2. Select the pen icon to start editing the article.

3. Make the changes.

4. Add a title and description explaining what changes you have made and why you made them.

5. Select Propose changes.

6. Select Create pull request to preview your PR.

7. Select Create pull request again to create the PR.

This is helpful to fix typing errors or add small things. If you are working on a larger update that includes pictures and editing files then it is not the best way to work. In that case, you will be better off creating a fork. See below for more thorough instructions on this approach.

Options 2: Creating a PR through a fork

There are a lot of great tutorials available online on how to fork a repository (GitHub), but we have also created a guide with instructions.

If you do not have Git installed on your machine, you should follow these instructions before you go any further.

Step 1: Creating a fork

Once you have set up Git you can create a fork of the Umbraco Documentation repository.

When you make a fork, you get a copy of the entire repository on your own GitHub profile.

You can create a fork by selecting the Fork option at the top of the screen:

Creating a fork

Once the fork has been created you will have your own copy of the Umbraco documentation. If you clone your fork, you will have the files locally which means you can make changes and sync them back up to your fork.

Are you adding a new article to the documentation? Add it to the SUMMARY.md file as well to ensure it is added to the navigation.

When you are satisfied with the changes you have made, you can submit a pull request to sync your copy with the original repository:

Fork of documentation

When you have had your fork for some time, you need to sync with the original repository before making new changes. This is called a rebase.

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

2. Fetch the updates.

3. Update your own fork.

git remote add upstream https://github.com/umbraco/UmbracoDocs/
git fetch upstream
git rebase upstream/main

This can also be done by using the Sync fork option, which will be present once your fork is behind the original repository.

Step 2: Creating a pull request

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

1. Navigate to the Code section on your fork.

2. Select Contribute and then Open pull request to get started.

Highlight option to contribute directly from fork to original repository.

1. Add a title and description explaining what changes you have made and why you made them.

2. Select Create pull request to create the pull request on the original repository.

Step 3: The review process

Your PR is now subject to review with the Umbraco HQ Documentation team.

We hope to review and resolve all incoming pull requests within a couple of weeks, depending on the extent of the changes.