Review and discuss a pull request
The review phase of a pull request typically involves reviewers making comments and the author pushing additional changes and commenting in response, until the pull request is ultimately approved. The pull request author usually starts by adding colleagues as reviewers. Reviewers then leave comments–either on the entire pull request or on a specific part of the code changes–and then updates their reviewer status to notify the author that they've completed their review. Create reminders within a pull request to ensure suggestions are incorporated by creating a pull request task.
Depending on the feedback provided by reviewers, the author may then update a pull request with new commits. This may be to clean up the code, resolve any outstanding tasks, or improve the quality of the code.
Once the cycles of reviewer feedback and new commits has reached a conclusion, a pull request can either be merged to its target branch, or declined if the changes are not to be merged.
Review a pull request
Bitbucket allows you to add one or more reviewers to a single pull request who can then approve (or reject) the request. Pull requests give those who maintain the repository the ability to review the quality of the code that’s specified in the pull request.
To review a pull request
- Access the pull request by either following links from an email notification, selecting a notification within the pull request inbox (in the upper-right), or searching for a pull request by clicking Pull requests on the sidebar (read more about searching for pull requests).
- Review the changes and comments left by your teammates within the pull request.
- Leave some feedback about the changes, in any of the views, and use @ mentions to ask questions directly of your colleagues, who will receive a notification after you enter your comment. See the Discuss a pull request section for more details about the various ways you can leave comments, including pull request tasks.
- Finish your review by indicating if you feel the pull request can be merged, or if the author of the pull needs to make additional changes before you can provide your stamp of approval. Select either the status indicators to let your team know you've reviewed the changes and the ball is now in their court:
- Approve - indicates you've reviewed the changes and the code is ready to be merged.
- Needs work - indicates you've reviewed the changes, but the code is not quite ready to be merged.
Create a Jira issue from a pull request
Bitbucket server allows you to create a Jira issue directly from a pull request comment instead of being forced to leaving Bitbucket and return with a created issue.
To create an issue from a pull request:
- Create a new issue by clicking Create Jira issue.
- Select the Project and Issue type.
- Add a summary and description and any other fields as needed.
- Click Create issue.
If a created issue is deleted inside Jira, it will continue to be counted as an issue, but will no longer be visible on the pull request.
This feature works best when used to create a spin-off issue to be dealt with after the pull request has been handled.
It is not recommended for adding more workflow items as part of the pull request.
Discuss a pull request
The most important aspect of a pull request is the discussion it generates. You can comment on the entire pull request, a particular file, or on specific lines of code in a file. Comment likes are a quick way of amplifying review feedback – effectively saying "also consider this person's feedback". You can also attach a task to any comment, so actions identified during the review can be easily tracked and resolved. Read more about pull request tasks.
There are three main ways to view changes:
- The overview tab - lists all of the activity for a pull request since the pull request was created.
- The diff tab - highlights which lines of code have been added, deleted, or modified.
- The commits tab - lists all the commits that will get merged. You can click to view a single commit.
The Overview tab captures all of the team's activity on the pull request in one place, right from the initial creation, through to when it is finally merged (or declined), with all the comments, replies and commits that happen along the way.
You can add a comment on the Overview tab (just under 'Activity'), or reply to a previous comment. Use mentions to alert another Bitbucket Server user to your comment, and use markdown to add formatting, for example headings or lists.
The diff view highlights the changes that will result when the merge occurs, so you can see exactly what the effect of the merge will be.
The Unified diff option from the Action menu shows the changes in one column.
The Side-by-side diff option from the Action menu lets you easily compare the changes that will be merged. Use the N (next) and P (previous) keyboard shortcuts to move between hunks in a diff. Use Shift+N (next) and Shift+P (previous) to move between comments in a diff. The 'map' in each margin of the side-by-side diff provides a visual summary of the diff hunks, and indicates which part of the file you're currently viewing:
Within the diff view you can select a specific commit to review, or choose to veiw all changes within a pull request. If you return to a pull request you previously reviewed, you'll only see the new commits added since you last reviewed the pull request. Iterative reviews are available in Bitbucket Server 4.11 or later.
The Commits tab lists all the commits that will get merged (those that are greyed out have already been merged). Clicking through to a commit leaves you inside the pull request context and the commit can be reviewed as part of the pull request..
When viewing a commit you can comment on the whole file, or a particular line of code, just as for a diff, for any file in the commit.
Participants can commit new changes to the branch. Bitbucket Server auto-updates the Commits tab of the pull request, so you can see exactly which commits will be merged. Bitbucket Server is smart about comments, moving them along when lines are added or removed. If a line with a comment gets removed, you can still view the comment in the activity, but Bitbucket Server marks the diff as outdated to let you know that this piece of code has been changed in recent commits.
View a single commit within a pull request
Use the Show diff of selector to switch between viewing a single commit, or viewing all the changes within a pull request. When you choose a commit from this menu only the files affected by the commit are shown. Switch back to viewing all the commits by selecting All changes in this pull request.
Pull request tasks
You can attach one or more tasks to any pull request comment, to track required work identified during a review. Anyone with permission to browse a pull request can create a task on any comment, and can browse, resolve or reopen existing tasks in the pull request. Repository admins and pull request authors can edit and delete any task in the pull request. Reviewers and others can only edit or delete their own tasks. A Bitbucket Server administrator can set a merge check that requires all tasks to be resolved before the pull request can be merged. See Checks for merging pull requests.
To create a pull request task, highlight some text in the comment, then click Create task – the task is automatically created and saved with that text. To indicate a pull request task is done, tick the box in front of the task.
To see all the unresolved tasks for a pull request, use Shift+T when viewing the pull request. Click the 'link' icon for a task to see the task in the context of the comment and source code.
Watching and notifications
You automatically get added as a watcher of a pull request when you are added to the pull request as a reviewer, or when you perform an action related to the pull request (such as adding a comment):
|Action||You're now a watcher|
|You are added as a reviewer|
|You add yourself as a reviewer|
|You comment on a pull request|
|You reply to a comment|
|You push to the source branch|
You can manually add yourself as a watcher by clicking the Watch button on the pull request screen.
You can stop watching a pull request by clicking the link in the email notification, or the Unwatch button on the pull request screen. If you stop watching a pull request you will not automatically be added as a watcher again if you subsequently perform an action that would otherwise have added you.
Bitbucket Server sends email notifications to watchers when certain pull request events occur. Email notifications are batched by default, but you can change your personal account settings (on the Notification settings tab) so you get notifications immediately. The following notifications however, are always sent immediately:
- To the reviewers when a pull request is created.
- To all watchers when a pull request is deleted.
- To a user when they are added as a reviewer to a pull request.
- To a user when they are removed as a reviewer from a pull request.
- To a user when they are mentioned in the description of a pull request.
See Notifications for details.