Review code in a pull request

Code review is an integral part of the pull request process, as well as the development process as a whole, and brings the following benefits to your organization and team:

• Knowledge sharing — Because all code is reviewed by someone knowledgeable, it gives more developers a chance to work on something new and get feedback from others.

• Quality assurance — Even experienced developers are always learning and could use a few extra eyes on their code to ensure high quality, error-free work.

• Mentorship opportunity — New users who have just started delving into the codebase can learn lots from the feedback more seasoned users can provide.

Reviewing code in a pull request has two parts: 1) looking at the changes made and comparing it to the original code and 2) adding comments and feedback to start a discussion about code. For more details about what it means to be a pull request reviewer, see Reviewers in Pull requests and code review.

Accessing the Activity feed

The Activity feed is available on the Overview tab of the pull request. Within the Activity feed you can start a review, add, reply to, resolve, or like a comment, and you can also create a task or a Jira issue (if Jira is integrated into your Bitbucket workspace). You can also filter the Activity feed by All activity, My comments, All comments, Tasks, Commits, or Statuses. Learn more about collaborating on code and providing feedback on pull requests.

Viewing file diffs

The Files changed tab displays a file tree on the left side of the page so you can access specific diffs right from the file tree.

Files changed filters and options

• You can filter the files changed view to display all changes, just the changes since last review, or select a specific commit or a selection of commits from the Commits list.

• Select the Comments dropdown to find and select a specific unresolved or resolved comment. You can expand and collapse those lists of comments in the dropdown.

• Sort the diff by either the files listed in the file tree or by recent comments.

Setting your default pull request (global diff view) settings

1. Access the pull request.

2. Select the Files changed tab.

3. Select the Settings button located in the upper-right corner of the pull request.

4. Update your global view settings for pull requests.

5. Select Save.

Pull request settings

• Diff view - Set your default diff view preference to either unified or side-by-side.

• Show - Select the various options below to display them within your pull request

  • Whitespace changes - Enable to show any changes in the file that involve spaces and tabs from the diff view, by default.

  • Word diff - Enable to display a darker shade of color on lines that have been updated or changed.

  • Color accessibility - Enable to change the background color of the diff to more visually accessible colors for people with color blindness. 

  • Annotations - Enable to display annotations by default in any pull requests.

• Load files

  • All at once - Enable to display all the files in the pull request by default.

  • Individually - Enable to individually display files in a pull request, by default, regardless of size.

• Tab size - Select a default size for tabs from the dropdown.

• File view - Select how your files will be displayed, by default, on the right sidebar in a pull request.

  • Tree - Displays the files in a hierarchical view.

  • List - Displays the files as a list.

Setting viewing preferences for each file

From each file, you can set the following viewing preferences from the More options... dropdown menu which can be accessed by clicking the More options... (meatball) button in the upper-right corner of the file (diff). 

Collaborate on code and provide feedback

Adding and viewing comments

Comments and discussion are a large part of the code review process. As authors and reviewers comment and reply to the discussion, the author might push additional commits until the pull request is ultimately approved.

Anyone with read access or higher to the repository can comment on a pull request. Pull requests have 3 different levels of comments:

• At the pull request as a whole

• On individual files

• On individual lines of code

Add comments to pull requests

To add multiple comments and tasks on a pull request

Whether you are adding comments or tasks on the pull request or directly on the diff, you can batch your comments and task together and only receive one email notification.

1. Add your comment and/or create a task.

2. Select the Start review button.

3. Continue to review the PR and add any other comments and tasks you would like to be part of your review by selecting Add comment.

4. When you are done adding all your comments and tasks, select Finish Review to submit the review.

   1. You can review your comments prior to submitting your review by selecting View all pending comments and tasks. This will open a preview of your comments and tasks.

   2. Approval status: As part of your review, you will need to select one of the approval statuses provided prior to submitting your review.

To add a comment at each level:

• Pull request – Under Comments on the pull request, click in the Add a comment text field. Add your comment and select Add comment now.

• Inline - Click the ‘+' associated with the line in the diff you want to comment on and/or add a task to > select Add comment now. Add your comment to the text field and click Save. You can also add a comment to the entire diff by selecting the Add comment button on the right side of the diff’s header.

Format your comments:

Use the WYSIWYG editor toolbar.

To mention another user:

You can mention another user by entering the @ symbol and typing / selecting that user's name.

To take action on comments:

You've got links below the comment that gives you some options:

• Reply - Keeps the conversation going by opening another comment field.

• Resolve - Resolves the comment thread. You and your team may use this to ensure all comments are addressed prior to approving or merging a pull request. Resolved comment threads will be collapsed in the diff by default.

• Edit - Reopens the comment field so you can make your updates and click Comment again. You can only edit your own comments.

• Delete - Permanently removes the comment from the pull request. Deleting a comment also removes it from the Activity.

• Like - Click to like the comment.

• Create task - Click to create a task for yourself or someone else who is a reviewer on the pull request.

• Reopen - You can always reopen a comment thread in case more action needs to be taken to get to a solution. If you need to open an outdated comment, you will need to go to the outdated comments associated with the diff and reopen the comment.

View and access comments on pull requests

You can always view comments on a pull request or inline with the file or a specific line of code, but you can also view comments and access comments from the Comments dropdown list or inline with the other actions taken on the pull request in Activity on the Overview tab.

Comments dropdown

Navigate resolved, unresolved, or outdated comments associated with the diff using the Comments dropdown available above the diff header.

1. Select the Comments dropdown. The number of unresolved comments on the diff is displayed on the dropdown.

2. To go to a particular comment in the diff, select the comment from the dropdown list.

The list is divided into unresolved and resolved comments with the unresolved comments listed first. Outdated comments will always be labeled as such within the comments list.

Create tasks

Add one or more tasks to a comment to track required changes. Anyone with ‘Read’ permissions or higher can create a task from a comment, not just the comment creator. Tasks give pull request authors a list of action items that they need to complete as part of their code updates. 

To create a task:

At the comment level: If the exact text you want to use for a task is in the comment, highlight the text and click Create task. Otherwise, click Create task under the comment, enter the task description, and click Save. These comments are contextual, so when you click on the link icon associated with the task in the right sidebar Tasks list, the comment will be highlighted on the pull request.

At the pull request level: Click on Create a task at the bottom of the Task card on the right sidebar. Type or add the task to the text field. Press Enter (Return) to save the task.

To see a list of tasks in the pull request:

Tasks are listed in the Task panel on the right sidebar. You can also find tasks listed in context in the Activity feed on the Overview tab.

Mark files as viewed

As a reviewer of a pull request, you can mark files you have reviewed as ‘viewed’ by selecting the Viewed checkbox on the diff (file) header. Once you have marked a file as ‘viewed’, that file will be collapsed and will remain in a collapsed state when or if you return to the pull request.

Approve a pull request

Anyone with ‘Read’ permissions or higher can approve a pull request.

To approve a pull request:

Within the pull request you would like to approve, select the Approve button in the upper-right corner of the pull request.

Accessing commits

To directly access a commit, select the Commits tab and select the commit from the provided list. You can also sync your commits from the Commits tab.