This guide to creating Git Pull Request Templates covers the importance of structure in Pull Requests and a downloadable template for teams. Templates like these play an important part in the product and engineering workflow.
A pull request is simply an event which signals the merging of code into a specific branch and gives engineers an opportunity to review and request changes to code.
In order for a PR to convey important information to product managers, designers, quality assurance, engineering managers and stakeholders, it’s important that it is readable to all. This is where pull request templates on leading platforms like GitHub, Gitlab and Bitbucket play an important role.
The lifecycle of a Pull Request:
A Pull request (PR) goes through distinct phases in its lifecycle. For example when an engineer creates a branch. It is common for it to have a draft status to inform other engineers in the team that work has started on a feature, bug fix or enhancement.
Once engineers have committed the required code needed for the software to behave and function to its proposed specifications, the PR status changes from draft to open. This is phase in the lifecycle where the Pull Request Template becomes critical to conveying important details to team members.
PR’s that have an open status, notify their assignee and reviewers that it’s ready for review. However reviewers are the one’s responsible for ensuring that code meets coding and documentation standards. Assignee’s on the other hand are added to either sense check code or are a part of the committers to the branch.
Possible Reasons for Code Change Requests
In the case of pull requests being unable to meet their acceptance criteria, there are several common reasons that can block incoming code from a merge. Below are some of them:
- Missing information from the pull request description or templated checklist
- Continuous integration tests failing
- Unit and Platform Tests failing
- Functionality not meeting design standards
- Functionality not meeting the acceptance criteria
- Unlinked to the original issue ticket
- Code reviewer concerns that are left as comments on the pull request.
The cycle of code changes can span from hours to many days. When the set criteria is met through comments, unit and CI tests. A PR is deemed as “ready to merge”.
A ready to merge state is achieved if all comments are resolved, the checklist in your pull request template is complete and a code reviewer approves the changes.
Once the code is merged into a deployed environment such as development, QA, feature or a production branch. It is ready to be tested for regressions, if the change is small enough that it doesn’t affect core functionality, it can go straight into production.
Let’s Git ship done 🚀
Track real-time updates on every code push and view Git insights – commits, blockers, and merges – all in one platform.
How to create a template for Pull Requests in GitHub, Gitlab and Bitbucket
Templates for pull requests can easily be created by anyone with write permissions inside a repository they have access to. It is not necessary for you to be an engineer in order to create one. The only thing you need is a basic understanding of markdown or you can use one of the many markdown converters like dillinger.io and browserling.com.
Pull Request Template for GitHub:
Step 1.
Navigate to github.com and then to your repo into which you intend to add the PR template.
Step 2.
In the root or main page of your repo. Click on Add File > Upload Files OR Create New if you want to edit the contents of the template or if you are unable to upload files into the repo. Upload files if you downloaded our Pull Request Template.
If you are uploading the Pull Request Template:
Step 3a.
Drag the file from your download folder and wait for it to upload. Once done, then click on commit changes.
Step 3b.
You are done! Your Pull Request Template is now live and ready to use.
If you don’t have permissions to upload a file to the repo or want to edit the contents of the template. Follow the steps below.
Step 3.
In the name field. Name your template “pull_request_template.md” . Naming your template anything else will not have it automatically show up when a new PR is created.
Step 4.
Paste the contents of your downloaded Pull Request Template into the editor and commit your changes.
Step 5:
Click on Commit new file at the bottom to push your changes.
Step 6:
Go to Pull Requests on the top nav bar and open a new Pull Request and your template is shown to engineers every single time.
For the readers of this post and our community of engineers and product leaders, we’ve created a downloadable template pre-written in markdown that can easily be shared with engineers or pushed directly as a commit into an existing code repo.
Merge Request Template for GitLab:
Step 1.
Navigate to gitlab.com and then to your repo into which you intend to add the MR template.
Step 2.
Click on the “+” icon and then select “New directory”
Step 3.
Now paste the follow path in the directory name input “.gitlab/merge_request_templates”
Step 4.
Now click on the “upload file” button and upload your merge request template that you downloaded.
Step 5.
Add a commit message that says “Upload Merge Request Template” and then click on upload file
Step 6.
Now create a new Merge Request and you’ll notice that a template shows up in the drop down for you to select. Select the template and continue with your merge request.
Effective communication through Pull Requests in Software Organizations
In smaller software organizations that have under 30 engineers, pull requests are often reviewed only by a senior engineer or tech lead; whereas in larger organizations the structure is quite different. In a larger company a pull request will convey more detailed information about the code being written and trigger a slew of events for the product, QA and release teams.
Since pull requests are such a crucial part of feature shipping, a PR for an established product & engineering team should convey the following information to the collaborating personas.
For Engineers and Engineering Managers:
Engineers consider pull requests as a daily event in their workflow. They are constantly creating, updating and responding to pull requests on a day to day basis. To an engineer, the following details must be present within the description of a pull request.
- A checklist of items that must be present as a part of the pull request. For example items such as the passing of tests locally, any ignored linter rules, etc.
- A summary of changes that are proposed in the pull request
- A link to the tara.ai task in the title of the pull request.
- A link to the design and intended behavior
- A short animated gif or video that demonstrates the feature functionality
For Designers
Designers can be involved in the Pull request review process, only if the information inside a pull request has an easy to understand structure. In order for them to find a pull request of value, it must contain references to designs and links to visual snapshots. Here are some of the recommended details that are important to designers in a pull request:
- A linked reference to the Figma, Invision, Sketch or Zeplin design.
- An integration with your visual testing software such as Chromatic, Percy, Screener IO or Applitools Eyes.
- A short video of the proposed functionality
When the request contains the above characteristics, designers can leave more thoughtful and actionable reviews to the pull request cycle. It enables designers to become a valuable and proactive contributor to the pull request workflow.
For Quality Assurance Engineers
The involvement of Quality Assurance (QA) engineers and regression testers in the pull request workflow is purely to be informed about an incoming change that will need to be tested. Quality Assurance engineers and regression testers for your software use the merged pull request as a reference to check it against exit and acceptance criteria. Data that QA engineers find valuable in a pull request is:
- A link to the Tara Task and/or Requirement that resides in google docs or Tara.ai requirements.
- Link to the designs and any click through prototypes
- A link to any BDD (Behavior Driven Development) specifications that are present in the Pull request. These can executable specifications written for BDD tools like Specflow and Cucumber
- Any proposals for automated E2E tests that engineers would like to be added once the pull request merges. \
For Product Managers:
Product Managers are also effectively key reviewers for Pull Requests. In a pull request, a product manager will usually look for a positive review from the engineering lead or code reviewer. The product manager’s involvement is similar to that of a collaborator on an issue ticket. Here are the following attributes that can help Product managers understand your PR better:
- A link to the Tara Task and/or Requirement that resides in google docs or Tara.ai requirements.
- A mention in the comments section if you require the product teams input
- A call out in the Pull Request template checklist that ensures that a product manager is informed a feature is close to being merged.
- A link to any decisions that were made to scope changes, this could be a comment thread, email or even a conversation in slack.
Using Tara.ai to accelerate your PR Workflow
Templates with clear and concise information are just one way of increasing your team’s feature velocity. Tara.ai’s GitHub and GitLab integrations provide visibility into the status so that Engineering Managers and Engineers can review and unblock PR’s quickly and effortlessly.
Once you’ve installed our verified Git integration (in one click), adding your Task ID to a branch auto-magically starts to populate status information for your open and draft PR’s. You can easily track the status of PR, how long it’s been open and when was the last commit to remind reviewers or your peers to get their code merged.
Most importantly, the no-code automation for premium users on tara.ai, autonomously changes the status of your ticket from doing to done. This helps engineers and product teams save hours every week, so they don’t have to chase down tickets that need updating.
Want to accelerate your software delivery even further? Sign up for free and get started with tara.ai today.
P.S Too busy to try us out? Click here to book a demo with a member of our team.