Templating Pull Requests & Merge Requests

How do you communicate with your team about proposed code changes?

Chore, Spikes, Features & Bugs

One of the most critical roles we play as developers is to clearly communicate with our team. When a change or addition is proposed to a codebase as a developer, I want the team members who review the code to understand what I was trying to achieve with that work. As a code reviewer, I want those who propose code changes to explain their changes and let me know me how to test the code.

Both GitHub or GitLab offer the ability to enable “templates” for proposed code changes. These templates are boilerplate text or other content that will automatically show up in the change request form when project collaborators issue a pull request or a merge request against a code repository.

Let’s talk about each service and how to work with them:

Creating Multiple GitHub Pull Request Templates for a Repository

Follow the below steps in order to create multiple pull request templates in GitHub:

1. In your repository’s root, create a directory named PULL_REQUEST_TEMPLATE. Do not name that directory anything else or put it in a different location, otherwise, GitHub will not recognize any of your templates
2. Place your template markdown files within PULL_REQUEST_TEMPLATE directory. Name these files as per your convenience e.g. Bug.md, Feature.md, Spike.md, Chore.md, etc.
3. Commit these changes and push it to your default branch.
4. While issuing a new pull request, add query string parameter template=name_of_template_file.md in the URL. This will auto populate the content of the template in description of the pull request as shown below.

https://github.com/apurvajain/ToDoList/compare/test?template=bug.md&expand=1

GitHub Pull Request with bug template provided in the query parameter

The process of manually adding query string parameter in GitHub is cumbersome 😫.

For more information, see GitHub’s documentation about URL structure, namely around query parameters (the ? in their URLs) for issues and pull requests.

Creating Multiple GitLab Pull Request Templates for a Repository

Creating multiple pull request templates in GitLab is pretty much straightforward:

1. In your repository’s root, create a directory named .gitlab
2. Inside of that .gitlab directory, create a directory named merge_request_templates.
3. Inside your .gitlab/merge_request_templates directory, add one or many template files, but they must be markdown files.
4. Commit these changes and push it to your default branch.
5. That’s it! 😎

When a contributor issues a new merge request, they’ll see a dropdown that encourages them to “choose a template” and pick which template suits their merge request.

GitLab Merge Request with bug template selected

Generic Pull/Merge Request Templates for Chore, Spike, Feature & Bug:

Following are the ready to use templates that you can easily import in your repositories and customise as needed.

Communicate better with Templates

By creating templates for pull and merge requests, we can help encourage contributors to communicate more effectively with their teams by noting what’s new or changed, give testing instructions to reviewers, or even help to ensure that code changes have been thoroughly vetted.

If you liked this post, please share, comment and give few 👏 😊