Creating a Pull Request

Owned by Stefan Prelle
Last updated: Jun 21, 2020
3 min read

A pull request means that you request the project maintainer to pull/include the changes you made into the main project. Before talking about how this is done technically, let us have a look on the politics/collaboration part behind this.

Etiquette

The main goals of the etiquette are:

  1. To prevent that you put time and effort in work, that is not accepted by the project maintainer.

  2. To track the work that is done in a way that it shows up in release notes.

Communicate, before you start

Before you actually start your work, ask the project maintainer whether they agree with the change/addition you are planning. A good way to do that is via Slack, which is explicitly used for contributor communication.

If the scope of your work is discussed - latest before you create a pull request - ask the maintainer to create an internal Jira ticket for your task and receive a ticket identifier (e.g. SR6-56)

Use Branches

A branch is a copy of the Git repository. Changes you make in one branch do not show up in the master-Branch (or any other branch). You can switch between branches. Branches are usually deleted again, after the work is done.

I strongly suggest that you create a branch for each task your are working on. This allows for picking which contributions are accepted and which are not.

Without working in branches, all your commits a combined in a way, that either all changes must be accepted or all must be denied - picking which changes to accept isn’t possible.

Add the ticket identifier in your commit messages

Having the ticket in the first line of your commit message, helps that all changes made to the code can be related to a specific task. E.g. if your commit message is “SPLIMO-58” , the tools would list this as follows:

In Bitbucket: Commit message links directly to ticket

In JIRA: Issue lists which commit messages deal are related

Creating a pull request

When your work is done and you a fairly sure and you verified that it is working as expected, it is time to let the maintainer include your code. Go the the webpage of the repository and navigate to “Pull requests”. In the upper right section of the screen, is a button to create a new pull request.

In the upcoming dialog, you need to select which of your branches you want to be pulled and which branch (usually “master”) of the main project it should be merged into.

In the title, enter the ticket identifier the maintainer gave you (see above). If you want a specific reviewer, you can define the person too.

If you hit the “Create pull request” button, the project maintainers are informed that there is a request waiting. We can’t make any promises on how fast we are reviewing it.