Using pull requests in Stash

Creating a pull request

When you are ready to start a discussion about your code changes, simply create a pull request.

To create a pull request:

1. You've pushed your changes to Stash, right?
2. Now, go to the repository in Stash. Either click Create pull request in the sidebar, or choose Compare from the Actions menu (when on the Source, Commits or Branches pages):
   
   
    
3. Choose the source and destination branches. The source branch is where you made your code changes and the destination is the branch you want to merge to. The source and target branches may be located in different forks:
   
   
    
4. Use the Diff and Commits tabs (see below) to compare the source and destination branches, before creating the pull request.
5. Click either Create pull request, or Continue, and enter a title and description that will help people understand what your pull request is about. You can use mentions (to notify another Stash user), and markdown (to add formatting) in your description.
6. Add reviewers – they will receive a notification by email. Other people who have permissions on the project can participate in the discussion if it interests them.
7. Click Create.

Discussing a pull request

The most important thing about a pull request is the discussion that it generates. To help you contribute to the discussion, Stash organises all the information about the pull request into 3 tabs. From a project repository page, click Pull requests, then click on a particular pull request.

Participants can commit new changes to the branch. Stash auto-updates the Commits tab of the pull request, so you can see exactly which commits will be merged. Stash 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 Stash marks the diff as outdated to let you know that this piece of code has been changed in recent commits.

Overview

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 (above the activity), or reply to a previous comment. Use mentions to alert another Stash user to your comment, and use markdown to add formatting, for example headings or lists.

Diff

Diffs for Stash pull requests provide the following advantages:

• The diff highlights the changes that will result when the merge occurs, so you can see exactly what the effect of the merge will be.
• The file tree on the left colour-codes files that have been added, changed or deleted, so you can quickly see the files you may need to review.
• As you'd expect, the diff for a file shows which lines of code have been added, deleted or modified.
• You can comment on the whole file by clicking the icon on the right in the diff header.
• You can comment directly on a line of code right in the diff, by hovering over the line, clicking the icon at the left, and entering your comment. Your comment will also appear in the activity.
• Comments in the diff are threaded, to allow meaningful and contextual conversations about your code.
• The Side-by-side diff option from the Action menu (arrowed below) 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:
  
  

• Search across all the files in a pull request, when viewing a pull request diff.

  The search looks at the diff and surrounding code lines to provide context. The file tree on the left displays only the files returned by the search.

  Use the 'f' keyboard shortcut to quickly access code search when viewing a diff in a pull request. The usual 'j' (next) and 'k' (previous) Stash shortcuts let you move between files in the search results. 'Esc' cancels the search.

Commits

The Commits tab lists all the commits that will get merged.

Note that clicking through to a commit takes you out of the pull request context; you can comment on the whole file, or a particular line of code, for any file in the commit.

JIRA issues integration

When Stash is integrated with JIRA you can see the related JIRA issues right in the pull request.  You'll see either the JIRA issue key, when there is just one, or the number of related issues:

Click an issue key to see details of the issue, such as the description, status and assignee, without having to leave Stash:

Click the issue key to see the issue in JIRA. This allows reviewers to gain important insight into the task that is being worked on, by seeing the comments and attachments on the issue. This also gives access into JIRA, so you can easily keep issues updated.

Merging a pull request

Once you are ready to merge a pull request, and when the reviewers have approved it, simply click Merge at the top right of the pull request view. You can merge a pull request if you have write (or admin) permission on the project.

Stash does not enforce particular review workflows, so, for example, anyone with write permission on the repository can merge a pull request, including the person who opened it. This flexibilty allows different teams to have different approaches to using Stash. If your team requires stricter control, consider using branch permissions to restrict who can merge a pull request to particular users or groups. You might also want to consider using a plugin to enforce a particular workflow, for example to ensure that only approvals from members of your review team allow merging. See Checks for merging pull requests.

In the 'Merge Pull Request' dialog, you can check Delete branch if you no longer need that branch in the repository. Stash checks on a few things before allowing the deletion – the branch being merged will not be deleted if:

• The branch is the default repository branch.
• The user does not have permission to delete the branch.
• The branch is subject to an open pull request.

Once accepted, the pull request is marked as merged on the Pull requests tab.

If Stash detects a conflict that prevents the merge, notifications are displayed on the Overview and Diff tabs of the pull request. Click More information to see instructions for how to resolve the conflict in your local repository.

Watching and notifications

You automatically get added as a watcher of a pull request when you perform an action related to the pull request, such as adding a comment. You can manually add yourself as a watcher by clicking the Watch button on the pull request screen.

You can always 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.

Stash sends email notifications to watchers when certain events occur. See Notifications for details.

Action	You are added as a watcher
You are added as a reviewer
You comment on a pull request
You reply to a comment
You push to the source branch
You approve the pull request