Write better PR's with this template 📄

Hey there!

So, recently I started in a new company where the process of reviewing code is not a critical part of the workflow, so I am developing a template for our pull request, in an atempt to improve our codebase and the process of reviewing a new change.

Why did I do this? Was it really necessary?

YES. I think a pull request should be a kind of documentation where you explain the context of your changes to your colleagues, not explaining the code, but explaining the business logic behind this change, why are you doing this work?

So I created a template for this, and set it as the default template every time you want to create a new PR.

Here is the template:

Context

Gives the reviewer some context about the work and why this change is being made, the WHY you are doing this. This field goes more into the product perspective.

Description

Provide a detailed description of how exactly this task will be accomplished. This can be something technical. What specific steps will be taken to achieve the goal? This should include details on service integration, job logic, implementation, etc.

Changes in the codebase

This is where becomes technical. Here is where you can be more focused on the engineering side of your solution. Include information about the functionality they are adding or modifying, as well as any refactoring or improvement of existing code.

Changes outside the codebase

If you have made changes to external services, need to add additional values to the job settings, or need to add something new to the database, explain it here. This may include updates to third-party services, changes to infrastructure configuration, integration with external APIs, etc.

Aditional information

Provide any additional information that might be useful to the reviewer in evaluating this pull request. This could include performance considerations,design choices, etc.

view raw pr_template.md hosted with ❤ by GitHub

Add the template as default in Github

And if you use Github, putting this as a PR template is super easy, you just need to create a file called pull_request_template.md and put it in the root of your project, or inside the .github folder.

You can see this with more details here: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository

That's all, I hope it can be helpful for you 🥳

Comments

[Mykhailo Toporkov 🇺🇦]

Have you considered using conventional commits system? You can ease enforce this just by set up pre-commit hook like husky with sth like:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

red=$(tput setaf 1) # ANSI escape code for red color
reset=$(tput sgr0)  # ANSI escape code to reset color

#Commit message check

commit_msg=$(git log -1 --pretty=%B)

if ! echo "$commit_msg" | grep -qE "^(feat|fix|chore|docs|test|style|refactor|perf|build|ci|revert)(\(.+?\))?:? .{1,}$
"; then
    echo "${red}Error${reset}: Invalid commit format, try: feat(feature): description." >&2
    exit 1
fi

if [ ${#commit_msg} -gt 88 ]; then
    echo "${red}Error${reset}: Invalid commit length. Your commit message is too long." >&2
    exit 1
fi

[Nico Montiel]

In a previous job, we used to use conventional commits, and it's an amazing practice to do so.
Thanks for sharing this script, I'm sure you'll make someone's life super easy with this 😄

[Paweł Ciosek]

Thank you! ♥️

[Pieces 🌟]

Thank you for sharing this! 🔥

[BeacampHQ]

Thanks for sharing ☺️

[Tam Minh Hoang]

Thank you!

[SUBARNAB SADHUKHAN]

Thank you Nico for sharing this insight🫱🏻‍🫲🏻.

[Antoniobox]

Awesome!!! 😍

[Justin Boyson]

Respectfully, I disagree. I believe PRs are the wrong place for this information. Once you merge this how do you ever find it again? I'm looking at the code in an editor 99% of the time. There is no context to this PR there. I would have to git blame the file then parse through all of the changes then go find the relevant PR.

A much better place for this information is in ADRs committed to the repo.

Document your Architectural Decisions in ADRs.
Document your code changes in your PR.

I think the Context section is great, but the Context and Description can be folded into one section. Plus I would add a testing/assertion plan to this, where it outlines how you assert that this PR does what it says. i.e. Log in, go to page, click thing see X. (Note this is separate from any automated testing. I want to know as a reviewer how do I personally confirm that what you're saying you did actually works)

That give me much more context as a reviewer and it forces your devs to not be lazy and not check their code before committing.

IMHO large boilerplate templates like this result in skimming and hand waving.