Opening a Pull Request

Once your change is complete and you’ve reached the definition of done, you're ready to open a pull request and start inviting project members to review it. You want the members to understand the aim of your pull request as quickly as possible. Therefore, you should provide as much detail as possible when opening a pull request.

Here you will find a few simple steps that you can follow when opening a pull request. If necessary, these steps can be altered and/or expanded depending on the requirements of the project you are working on.

Provide a short summary title

A short summary title allows the reviewers to get a brief idea of what they're going to review. It also allows a pull request to be found with ease, which is a great help when working on a project which has many open pull requests. Try to describe the change is in as few words as possible as long titles will usually get truncated.

When using an issue tracking system, including the issue number at the beginning of the title is a good idea. This will allow the reviewers to find all the relevant information, such as acceptance criteria, steps to reproduce, required credentials, etc. Many version control repository hosts are able to detect issue numbers and link them directly to the issue itself.

Use the description box

If not using an issue tracking system, you can add any extra information into the pull request description box. The description box is also a good place to provide explanations for decisions made during your change. This is especially helpful if your change is complex or has some changes that you know could raise eyebrows.

As well as providing steps to reach functionality, required credentials, known issues, etc, you can also provide screenshots and/or screen recordings if you have made a change to the UI. It is advisable to add both before and after screenshots and/or screen recordings. This will allow for other project members to easier visualise the change and may help you spot undesired results.

Review your own pull request

Most pull requests systems will allow you to check your own pull request before opening and sharing it with other project members. Doing this step will give you an overview of your whole change. You will often discover accidentally committed code, commented out code, overcomplicated logic, amongst many other things you may wish the other project members didn’t see.

You can also take this moment to add comments to your pull request. This way, you can pre-empt questions that reviewers will ask, add links to documentation or blog posts that explain your solution. Or even to ask reviewers for a better solution if you believe your own is not optimal.

You should review your own change just the same as the other project members will review it. To find out more about how to review a pull request you can read our post about it here.