Syncfusion prefers a Git workflow for managing all our complex products across a variety of platforms. Our day-to-day work has been simplified since adopting the Gitflow model in our development phases.I am assuming the readers of this post are already familiar with the basics of Gitflow and also aware of the importance of pull requests on each development phase.

As developers, our responsibility is not only to fix issues or implement new features, but to clearly communicate the development work to reviewers. A developer can convey proposed code changes and their purposes either through detailed documentation or other means of communication.

Here’s where the inevitable descriptions of pull or merge requests come into play, where the code contributors share detailed comments on their code.

The GitKraken team thoughtfully considers team collaboration when developing its tools: the GitKraken Git client and Glo Boards. There are numerous opportunities to add significant context to your file changes and pull requests from within GitKraken, which supports pull request templates committed to remote repos on GitHub, GitLab, or VSTS (including Azure DevOps with legacy VSTS URLs). More on that later…

What Role Does a Description Play in a Pull Request?

Providing descriptions for pull requests is highly recommended for a better code review process. Descriptions clearly answer:

• What can reviewers expect while reviewing the submitted code?
• What standards has the developer considered before submitting their code for review?

Later, the reviewers can initiate an open discussion between themselves and the developers to track every code change before those changes are pushed into repositories.

Description Checklist

To make a pull request as clear as possible, it should include an appropriate checklist of relevant information about the proposed code changes (instead of a single line summary), such as:

• How a bug was fixed and a description for the  solution.
• A description or summary of a new feature.
• The unit test cases covered.
• Whether this code breaks existing functionalities.
• Any testing details.
• Whether it was tested in all devices and browsers.

Wouldn’t it be nice if these checklists showed up automatically in the description field every time you made a new pull request? Good news! The Gitflow model offers this ability through the template option.

And better yet, GitKraken makes it painlessly easy to access your templates throughout your workflow. We will review exactly how to utilize pull request templates in GitKraken later in the article.

You can see an example of how these descriptions are viewed in a pull request in the following image.

What is a Pull Request Template?

When you initiate a new pull request for an implemented feature or a bug fix in your project repository, you can allow the description field to pre-populate with  a checklist of items relevant to your team, like the checklist provided in the previous section. This process of exhibiting the pre-filled description field in pull request form is often referred to as a Pull Request or Merge Request Template.

For an automatic pre-population of details in the description field, you must first define your own set of templates and then add them to the project’s root directory. You can also create multiple templates separately for bugs, features, documentation, etc..

The description templates are usually drafted as Markdown files and should be added to the appropriate directory of your project repository. The naming of a directory, as well as the handling of single and multiple templates in your project repositories, differs based on what service you prefer to use: GitHub or GitLab. For the purposes of this article, we are going to focus on GitHub.

NOTE: Refer to the Markdown documentation for how to write content in Markdown files from the syntax guidelines provided.

As an example, you can reference the checklist defined in a Markdown file, making use of the task list syntax shown in the following screenshot.

The same task list will be displayed in the submitted merge request page as follows.

How to Create a Single Pull Request Template in GitHub

If your project repository is on GitHub, the name of the template and where it’s located in your repository matters a lot. The template created as a Markdown file should be named PULL_REQUEST_TEMPLATE.md by default and placed in either the project’s root folder or .github directory.

Create a Markdown file, name it PULL_REQUEST_TEMPLATE.md, and place it in the project’s root folder.

Or, create a directory, name it .github, and place the Markdown file in this folder.

NOTE: Make sure to place the Markdown file within one of the previously mentioned locations and save and merge it with the same name.

Now, when you create a new pull request, you will see the template content automatically loaded into the description field as shown in the following image.

Utilizing Pull Request Templates in GitKraken

As we briefly mentioned earlier, GitKraken supports pull request templates committed to remote repos on GitHub, GitLab, or VSTS (including Azure DevOps with legacy VSTS URLs).

When you create a new pull request in GitKraken, the Pull Request Template drop-down menu will appear, allowing you to select a pull request you have created in one of your repositories. This allows you to easily and quickly fill in your pull request using all the information designated on your pre-drafted template.  

How to Create Multiple Pull Request Templates in GitHub

It wouldn’t be sensible to use the same description template for different categories of pull requests. For example, you may need to initiate a pull request for submitting the code changes of a newly implemented feature, a simple bug fix, documentation, or any kind of configuration work. It would be best for each of these pull request links to load and pre-populate different template contents in the description fields based on the submitted pull request category.

To make use of different templates, you must first create multiple template files and save them as separate Markdown files in your repository, as explained in the following steps:

1. Create a folder named PULL_REQUEST_TEMPLATE and place it within either the root directory or the directory named .github.
2. Create multiple template Markdown files and place them all in the folder PULL_REQUEST_TEMPLATE.

NOTE: The Markdown files created in this process can be named as you choose, but the folder mentioned in the first step must have the name PULL_REQUEST_TEMPLATE.

If you do have multiple template files in GitHub, you will always need to manually navigate to the URL of the specific Markdown file you want to pre-populate in the pull request form.

For example, I’m creating a Markdown file and naming it bug-template.md. I place it in the PULL_REQUEST_TEMPLATE folder of my main repository. When I want to push some changes into this main repository, I will initiate a new pull request. To pre-populate my pull request form with the content of the bug-template.md file, I need to navigate to the URL by passing an additional template parameter:

https://github.com/Scheduler_Project/compare/master…Test_branch?expand=1&template=bug-template.md

Here, Scheduler-Project refers to the name of my main repository and I’m trying to merge the code changes from the Test_branch into my master branch. At the end of the URL, there’s template=bug-template.md to pre-populate the content of the bug-template.md file into my pull request form.

NOTE: You can also refer to the GitHub help documentation, which explains how to use template query parameters in the URL.

Now, after making these URL changes, you can see the description content being loaded in the pull request form as follows.

You can edit the previous description with relevant details and click the Create pull request button, which will open your submitted pull request page as follows.

Creating Merge Request Templates in GitLab

Unlike the GitHub repositories, GitLab allows you to choose from multiple templates in the user interface of the merge request form.

You can see more information on this in the GitLab support docs.

Conclusion

GitHub and GitLab provide a better way to create predefined templates for pull requests. The template options offered by both allow developers to share accurate details of their proposed code changes at the start of the review process. Providing clearer code descriptions makes the code review process easier, which in turn helps achieve better code quality and limits the risks of unnoticed mistakes.

Once you take the time to create pull request templates in your repo, you and your team can utilize them on an ongoing basis when working inside GitKraken—saving you time, decreasing context switching, encouraging consistency, and increasing productivity.