Pull requests let you tell others about changes you've pushed to a repository on GitHub Enterprise. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.
This guide walks through the process of sending a hypothetical pull request and using the various code review and management tools to take the change to completion.
Before you begin
This guide assumes that you have a GitHub Enterprise account, that you've forked an existing repository, and that you've pushed changes to your fork. For help with forking and pushing changes, see the Forking a Repo article.
Initiating the pull request
In the following example, Hubot has completed some work on a fork of the Octocat's Spoon-Knife repository, pushed a commit to a topic branch in his fork, and would like someone to review and merge.
Navigate to your repository with the changes you want someone else to pull and press the Pull Request button.
- Switch to your branch
- Click the Compare & review button
You can send pull requests from any branch or commit but we recommend that you use a topic branch. That way, you can push follow-up commits if you need to update the pull request.
Reviewing the pull request
After starting the review, you're presented with a review page where you can get a high-level overview of the changes between your branch and the repository's master branch. You can review all comments made on commits, identify which files changed, and get a list of contributors to your branch.
Changing the branch range and destination repository
By default, pull requests are based on the parent repository's default branch. In this case, the hubot/Spoon-Knife repository was forked from octocat/Spoon-Knife so the pull request is based on the master branch of the octocat/Spoon-Knife repository.
If the default parent repository isn't correct, you can change both the parent repository and the branch with the drop-down lists. You can also swap your head and base with the drop-down lists to establish diffs between reference points. References here must be branch names in your GitHub repository.
The easiest way of thinking about the branch range is this: the base branch is where you think changes should be applied, the head branch is what you would like to be applied.
When you change the base repository, you also change notifications for the pull request. Everyone that can push to the base repository will receive an email notification and see the new pull request in their dashboard the next time they sign in.
When you change any of the info in the branch range, the commit and files changed preview areas will update to show your new range.
Using the compare view, you can set up comparisons across any arbitrary timeframe.
Sending the pull request
When you're ready to submit your pull request, click Create pull request.
- Enter a title and optional description in the discussion page. In this view, you can see the commits that are included once you send the pull request.
- Make any necessary customizations to the commit range and review the commits and file changes.
- Click the Create pull request button.
After you send a pull request, any commit that's pushed to your branch will be automatically added to your pull request, which is useful if you're making additional changes.
Managing pull requests
In the request dashboard, you can browse pull requests that you've sent or received. You can also view pull requests for any repository to which you have access via the Pull Requests page.
The pull request dashboard and the repository pull request list have filtering and sorting controls that you can use to narrow down the list to the pull requests you're interested in.
Reviewing proposed changes
Once you receive a pull request, you can review the proposed changes. The commits in the pull request show you what will be merged with the underlying git repository if the pull request is accepted.
You can also review the cumulative diff of all file changes across all commits, either split or unified.
Pull request discussion
After reviewing the basic description, commits, and cumulative diff, the person tasked with applying the changes may have questions or comments. Perhaps the coding style doesn't match project guideline, or the change is missing unit tests, or maybe everything looks great and some props are in order. The discussion view encourages and captures this type of discussion.
The discussion view begins with the pull request's original title and description and then chronologically lists additional activity. The following types of activity are captured as they occur:
- Comments left on the pull request itself
- Additional commits pushed to the pull request's branch
- File and line notes left on any of the commits included in the pull request's range
Pull request comments are Markdown compatible so you can embed images, use pre-formatted text blocks, and perform other formatting supported by Markdown.
Viewing long-running pull requests
When a pull request seems to linger for an extended period of time without making any progress, you may want to review it to understand what's blocking it from being resolved. You can find still-active pull requests by viewing and sorting long-running pull requests from your repository's Pull Request page.
Long-running pull requests exist for more than a month and have seen activity within the past month. This filter displays those long-running pull requests sorted by life span: the amount of time from creation to the most recent activity.
