What Exactly Is a Pull Request Template?
A pull request template is a document with Markdown content included in your pull request description when creating a pull request.
Writing compelling descriptions for pull requests is an excellent way to guide reviewers in understanding what to anticipate when examining code. Additionally, it serves as a helpful method for keeping track of essential tasks for each modification, like testing, incorporating unit tests, and revising documentation. Utilizing pull request templates can assist your developers in crafting exceptional pull request descriptions that align with your company’s criteria.
Listed below are the types of pull request templates you can create with Azure Repos
- A default pull request template: This is automatically used for all new pull requests in the repository unless a branch-specific pull request template overrides it.
- Branch-specific pull request templates: These are automatically used for pull requests directed at a particular branch.
- Additional pull request templates: These can be optionally added by the pull request author.
The location for all pull request template files should be your repository’s default branch (usually main). Pull request template files from the default branch are the only ones that will be used.
Default Pull Request Templates
When a new pull request is created, the description field will automatically contain the default pull request templates. To set up your repository with a default pull request template, save a file named pull_request_template.md or pull_request_template.txt in the default branch of your repository in one of the specified folders.
- .azuredevops at the root folder of your repository
- .vsts at the root folder of your repository
- docs at the root folder of your repository
- The root folder of your repository
When a repository has a new pull request, the information from the default pull request template is utilized to automatically fill in the description field of the pull request.
Branch-specific Pull Request Templates
To set up pull request templates specific to branches, you can create a .txt or .md file named after the branch you want to target. The file name should match the first level of the branch name, such as main, dev, release, or feature. Each branch-specific pull request template will be used whenever a pull request targets that branch or any of its sub-branches. For instance, a pull request template named twc.md will be used if a pull request is aimed at the twc branch or any twc/* branches.
Make sure to save branch-specific pull request templates in the default branch of your repository. Use the following folder hierarchy: pull_request_template/branches/. These folders should be located within one of the following specified folders in your repository.
- .azuredevops at the root folder of your repository
- .vsts at the root folder of your repository
- docs at the root folder of your repository
- The root folder of your repository
For instance, a pull request template specific to a branch that should be used for all pull requests merging into the dev branch would be titled dev.md or dev.txt and placed in one of these locations.
- <repository root>/.azuredevops/pull_request_template/branches/
- <repository root>/.vsts/pull_request_template/branches/
- <repository root>/docs/pull_request_template/branches/
- <repository root>/pull_request_template/branches/
Additional Pull Request Templates
You can configure extra pull request templates in addition to the default and branch-specific ones. These templates should be located in the .md or .txt format and placed in one of the specified folders on your default branch.
- <repository root>/.azuredevops/pull_request_template/
- <repository root>/.vsts/pull_request_template/
- <repository root>/docs/pull_request_template/
- <repository root>/pull_request_template/
When you create a pull request, you can add any existing pull request templates by selecting them from the drop-down menu labeled “Add a template.” The options in the menu correspond to the file names of the templates.
In conclusion, pull request templates are not just tools, but valuable assets that provide structure and guidance to your development team. By using the default, branch-specific, and additional templates, you can streamline the pull request process and ensure consistent and thorough pull request descriptions, instilling confidence in your team’s code contributions.