Merge Request Templates

Welcome to Tanuki Tuesday, where I look at the features offered by GitLab.
This week I'm going to look at merge request templates, and how they can help guide users through providing the required information to get their changes merged into other branches.

I've previously covered issue templates. Merge request templates work in a very similar manner, but for selection during creating merge requests.
The best way (I've found) to use them, is to give contributors a checklist of things to cover as part of their submission. This can also be used by the reviewer or maintainer to ensure everything is present and correct ahead of accepting the change.

What Are Merge Request Templates

Like issue templates, merge request templates are pre-defined layouts for use when creating a merge request within GitLab.
If you have them set up in your project repository, then they are available during the merge request process for selection to use.

Creating Merge Request Templates

Merge request templates are written in markdown. They exist as .md files within your project repository.
Create a template in the .gitlab/merge_request_templates folder (you may need to create the folder first) and, once it is on your default branch, it will be available when creating new merge requests.

The templates use Gitlab Flavored Markdown, which is an extension of standard Markdown.

Comments are hidden from the preview and rendered displays, and are just use HTML comments e.g. <!-- this is a comment !-->.

A commonly used method of ensuring each merge request goes through the same process is to use checklists within the template.
Checkboxes can be created by starting a line with - [ ], followed by any text.
GitLab use this to great effect in their default merge request template, from which the snippet below was taken:

### Conformity

- [ ] [Changelog entry](https://docs.gitlab.com/ee/development/changelog.html) 
- [ ] [Documentation](https://docs.gitlab.com/ee/development/documentation/workflow.html) ([if required](https://docs.gitlab.com/ee/development/documentation/workflow.html#when-documentation-is-required))
- [ ] [Code review guidelines](https://docs.gitlab.com/ee/development/code_review.html)
- [ ] [Merge request performance guidelines](https://docs.gitlab.com/ee/development/merge_request_performance_guidelines.html)
- [ ] [Style guides](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/development/contributing/style_guides.md)
- [ ] [Database guides](https://docs.gitlab.com/ee/development/README.html#database-guides)
- [ ] [Separation of EE specific content](https://docs.gitlab.com/ee/development/ee_features.html#separation-of-ee-code)

This results in the following output when the markdown has been saved (except the strike-throughs - this image was taken from an in-progress merge request):

Why Use Merge Request Templates?

Giving users the guidance to ensure everything is in order ahead of a review should increase the likelihood the change is merged sooner.

Merge request templates are another area where you can use scoped labels to help improve the efficiency of your workflow.
Creating a merge request relating to Security? Use /assign ... to assign it to someone in the security team to review (see my quick actions post for more details on this).
Doing this on a template means even new starters can have their work reviewed by the right person rather than involving their team lead just to change the assignee.
Having different merge requests for different types of requests can reduce the amount of training needed to get someone new to their most productive when contributing to the project.

Conclusion

Merge requests are stressful for both the submitter and the reviewer.
There's so much to remember, and so much depending on a successful outcome.
Using merge request templates can help reduce that stress on both side, especially by using checklists.
Add the absolute requirements for a submission, and everyone has their expectations set.
If there's some items not ticked off, it's likely not ready to merge.
When a reviewer is looking at the request, they can work through the list and ensure everything has been done.

An added bonus is that if the process changes, such as a new task being added, then the template can be updated.
Everyone who is submitting following the process change can follow it using the new list.
There's full transparency of the process for merge requests, and people won't feel cheated for missing steps which have not been documented.

Reduce the cognitive load on everyone in the process, and increase the chances of a successful merge.
What more could you want?
Merge request templates facilitate that.