Memory. The mortal enemy of all software developers. We don’t like things that require remembering or using our memory. We prefer to automate, eliminate duplication, and avoid functions that require us to trust other people.
Creating a new pull request is a showcase of our own work. In a pull request, we expose our hidden work to the rest of the team, and they will spend their time judging it. It is good to be well-prepared to receive criticism of our work, and the second-best option (besides automation) is to use some kind of list to aid our memory.
Pull Request Templates
Azure DevOps and GitHub both supports pull request template files. These are special files in repository, which are used to generate description template when new pull request is created. Files can use Markdown language to describe things with tables, headers and checklists and the checklist is the one that we are most interested of.
Why Would I Use Templates?
Pull request templates help manage the manual steps in software development.
- You Can’t Automate Everything: Some tasks, like updating Jira tickets or work items, still require manual effort.
- Avoid Relying on Memory: A checklist in the template helps ensure you don’t forget these important manual steps.
- Keep It Short: A concise template is less distracting and more effective for everyone.
Using pull request templates can make manual processes easier to manage and less error prone for moderation.
Azure DevOps Templates
In Azure DevOps (and in GitHub too actually) you have to create a file called pull_request_template.md to use the templates. You can use other names also, but then the naming convention will try to match filename with the targeted branch name. For example feature.md would match all pull requests that are targeting feature or feature* named branches. For default branch use the pull_request_template.md.
For my use case I wanted to have a checklist of things, that cannot be automatically checked before pull request is created. These are things like “is the Jira ticket up-to-date” and “have you updated project documentation”. By using Markdown language and PR templates, we can build this kind of checklist quite easily:
## Checklist for Pull Request - [ ] I have implemented unit tests for suitable code parts - [ ] I have updated work item and added neccessary comments - [ ] I have updated the project documentation if it was neccessary
Save the Markdown file as pull_request_template.md, store it in suitable directory (I decided to use .azuredevops at the root level) and push it into master. This Markdown will produce us a nice short checklist for every pull request that is done against default branch (main or master).
You can place the markdown file under following folders:
- A folder named
.azuredevopsthat is contained in the root folder of the repository - A folder named
.vststhat is contained in the root folder of the repository - A folder named
docsthat is contained in the root folder of the repository - The root folder of the repository
Additional templates
You can also add additional templates that can be applied in special cases. Problem with these are of course that they require memory. You need to remember to apply them when you are creating new pull request. To use the additional templates create folder called pull_request_template under any of the folders mentioned above. Then add template files of your choise into folder and merge it to default branch.
Additional templates are shown in Add a template dropdown. Applying additional template will append the content of the MD file in pull request description textbox. Yes you can click it multiple times to append it more than once. There is no extra logic behind it.
Summary
If you have problems in pull requests that your team members are forgetting things: They don’t update tickets or they don’t add translations for all the UI texts, then add simple template file that reminds them to do it. Don’t waste your time on banging the drum over and over if no one is listening. Apply steps of automation to ensure that things are happening when they should.