Pull Request Templates (GitHub, Bitbucket)

If you're into tech and follow my blogs, there's a high chance you've worked with version control systems with tools like Github, Gitlab, Bitbucket, etc. One of the common use cases is working on feature/bug and getting your code merged for production deployments. Pull Request is a view of the changes made across codebase. Most often, there is a standard process of getting your PR (pull request) reviewed aka code review.

From my professional experience, I've personally found code reviews to be extremely helpful. It's one of the best ways to enhance your low level coding skills. But, code reviews are helpful only when the reviewers have some context about the problem being solved. Hence, to communicate properly about the changes made, how the solution has evolved, what best practices one follows across the team, all these are assumptions that people have when they raise a PR. As a dev, it's your job to give appropriate context - remember everyone has tons of tasks, to make the task of code review simpler and faster - it only makes sense to add relevant information.

Pull Request template is basically a structured format usually across team that help in conveying required information and guidelines about the changes to the reviewers.

Benefits of using Pull Request template

• Standard format of template for pull requests across team/org. Helps in using PR descriptions as a habit.
• Better tracking of changes across team. Since single PR contains info, comments section helps in communicating updates on the PR across team.
• When you list down changes - it helps to avoid missing on small things like config changes (one of the most common reason for prod issues), etc.
• This streamlines the code review process, improves code quality, and saves time too!

Not everything is green, adding this sometime leads to fatigue in team filling PR descriptions for very small changes - this varies on how team members are comfortable and not making misses. So try and then iterate with changes as it suites the team. Very small team don't need this generally since everyone has good context of things. But in large teams, the benefits of PRs seem much more promising.

How to create your own template

Enough talk? Let's curate a template with some relevant requirements. Later, we'll see how to create it on Github, etc.

There are some common sections to include in your PR template.

• Type of PR
• Description of the changes
• Relevant tracking tickets & links to documents (PRD, Tech spec)
• Tests Coverage
• Documentation
• Post-deployment tasks (Monitoring/ Rollback)

Initially, I started with a relatively shorter template but with growing team size, it has evolved to this stage. Obviously, initial version were built using template on open source repos and guides.

# Description

Add summary of the changes. Include relevant motivation, context and success metrics for this. List any dependencies that are required for this change.

- Type: Bug Fix | New feature | Tech enhancement
- JIRA: <link to ticket>
- PRD: <product requirement doc>
- Tech spec: <tech solution doc>

## Test Case Coverage

- Code coverage change (old - new):
- <QA test coverage doc>

## Config changes

- `CONFIG_NAME`
- new s3 config added - `example.json`

# Checklist:

- [ ] Code is compiled and generates no new warnings
- [ ] My code follows the style [guidelines]("link to guidelines") of this project
- [ ] Code self-review
- [ ] Added comments where required in code.
- [ ] Created/updated the documentation. <link>
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream modules

# Success Metric

How this changes affects tech/business metric. Where/How can it be tracked?

- <link>

Template is straightforward and self explanatory. Obviously, this can be changed based on existing systems you use in your team.

Creating a template on Github

Assuming your repository is already on github, if not you create one and push changes. Now adding PR template is pretty easy.

Create a file named PULL_REQUEST_TEMPLATE.md and place it one of three locations:

• root of your project
• .github folder (if you want template to be in hidden directory)
• docs folder (common practise)

Now commit and push your changes. GitHub automatically detects the PULL_REQUEST_TEMPLATE.md file and will auto-populate all new PRs with the template.

Here's a list of commands for creating and pushing changes. Check my blog on branching to learn how to work with branches in git.

git checkout -b add-pr-template
cd .github
vi PULL_REQUEST_TEMPLATE.md
git add .
git commit -m "Add PR template"
git push origin add-pr-template
# create a PR and merge to master branch

Creating a template in Gitlab

Creating PR template is very similar to that of Github. Only difference is the way we are storing it. For gitlab, just create your markdown file in following directory.

├── .gitlab/
    ├── merge_request_templates/
        ├──merge-request-templates.md

Gitlab shows a dropdown, so you can add multiple types of templates based on requirements.

Resources

• Explore various PR templates
• Creating PR template - Github
• Book: Pro Git

Do explore articles on Golang and System Design. You'll learn something new 💡

Liked the article? Consider supporting me ☕️

I share regular updates and resources on Twitter. Let's connect!

Keep exploring 🔎 Keep learning 🚀