Git Pull Requests

Terms

Repo/Repository - A Git Repository, or Repo, is a data structure that Git uses to track the history of a set of files.

Fork - A Fork is a copy of a repo. A Fork allows you to freely make changes to a repo without affecting the original, and is commonly used to propose changes to someone else's repo, or as a starting point for your own repo.

Branch - A Git Branch is a pointer to a snapshot of the repo at a specific point. When a Branch is created, a new pointer is created in the repo that points to the latest commit in the Branch that the new Branch was created from. It will share the same commit history as the original Branch up to that point, but any commits made in the new Branch will be unique to that Branch.

Commit - A Commit is a snapshot of a change (or changes) to a file (or files) at a specific point that becomes part of the repo's history.

Pull Request - A Pull Request is a notification to others that you have made some changes to a repo, so that they can consider implementing the same changes in their own repo.

Overview

You have fixed a bug or added a feature in your local Engine source code… Now what? Many UE4 developers and hobbyists have been submitting fixes and new features for the Engine through Pull Requests on GitHub ever since Unreal Engine was first launched.

Creating a Pull Request and submitting your own fix or feature is easy. Here is a quick explanation of how to send us a Pull Request.

Create a New Branch

First, make sure your fork of the repo is up to date and you have switched to the Master branch. While it is possible for Epic Staff to review a Pull Request that was made in another branch, using the Master branch does make it easier for us. Once you are in the Master branch, create a new branch that will contain only your changes. You want to make sure nothing else is changed in this branch, or it will also be included in the Pull Request.

Make Your Change in the New Branch

Once you have created your new branch, sync your local repo so that the new branch is available on your local machine. If you are working with the GitHub Desktop software, you can get the new branch in your local repo by clicking the Sync button towards the top right of the window. If you are using the command line, run the command "git fetch origin", which will retrieve, but not merge, any changes from the GitHub server that are not present in your local repo.

Make sure that you are working in your new branch and apply your changes to the source code. Compile the Engine with your changes included and make sure the issue you are fixing is actually corrected, or that your new feature works as intended. Once you are done, make sure to sync your GitHub repo to include the changes you made locally. In this example, I made a minor change to the README file in the repo.

Create a New Pull Request

Once you have updated all of the files that you want to change and committed them into your new branch, you can create a new Pull Request. There are a couple buttons that will accomplish this. First, GitHub may show a list of “Your recently pushed branches.” If so, you can click the “Compare & Pull Request” button for the branch your changes were made in. If GitHub does not show these branches, you can click the “New Pull Request” button next to where you select the branch you are looking at.

When you click one of these two buttons, you will be taken to a page where you will be able to open a new Pull Request. This page will compare the base fork (this is the fork that you are proposing the changes be merged into, which is automatically set to our Unreal Engine repo) with the head fork (this is the fork where the changes currently exist, which is automatically set to your fork of the Unreal Engine repo). The page will also specify which branches in the base and head forks are being compared. Since the Release branch is the default branch in the Unreal Engine repo, this is automatically selected in the base fork. You will want to make sure you change the base branch to the Master branch (or whichever branch you used when you originally created your new branch). If you do not, you will see a message saying that GitHub cannot automatically merge the changes. You can still submit the Pull Request in this case, but if you do there will be a large number of additional commits included in your Pull Request due to the differences between the branches, which will make it somewhat more difficult for us to isolate your changes in order to review them. The differences between the Release and Master branches are explained here.

If you were already looking at your new branch when you clicked one of the buttons above, this branch will already be selected for you. Otherwise, you can change the compare branch to the branch that contains your changes.

Enter a title for your Pull Request that clearly summarizes what the Pull Request is intended to accomplish, and optionally add in a more detailed description of what your Pull Request does. At the bottom of the page, you will also see a list of the commit(s) that will be included in the Pull Request, as well as the changes to any files that the Pull Request makes.

Once everything looks good (you can still edit most of this later), click the Create Pull Request button, and you will be all set. Once Epic receives the Pull Request, we will have one of our Engineers review your proposed changes and decide if we want to include those changes in the Engine. Depending on workload and the complexity of your changes, this review process may take some time.

We appreciate you putting in the effort to help us continue to improve Unreal Engine 4. Even if we ultimately decide not to incorporate the changes that you suggested in your Pull Request, your Pull Request has most likely pointed out an area that we need to look into more closely.

Some Things to Keep in Mind

When you are making your changes to submit as part of a Pull Request, you will want to make sure that you keep the Unreal Engine Coding Standard in mind. This document describes the standard that we try to maintain within the Engine code, and we generally try to make sure Pull Requests follow this standard as well. If your Pull Request does not follow the standard, you may be asked to update the Pull Request to meet the standard.

Additionally, we prefer to have each Pull Request provide a single fix or feature. A Pull Request may involve changes to multiple files, and may include multiple commits as well, but the goal is that the Pull Request encompasses a single idea. If you want to provide multiple fixes and/or features, we would prefer it if you submitted multiple Pull Requests instead of including them all in a single Pull Request. Keep in mind that ideally each Pull Request will be in its own separate branch in order to make sure the only commits included are the ones involving that particular change.

-- () 19:51, 6 July 2017 (UTC)