The world is a much better place with Git. Can you imagine working on a tech or data project without Git? Oh man, it’s scary 😨
For people who are not very familiar with Git, it’s a life-saving tool that helps you track changes to your code over time, aids in reviewing each other’s contributions when collaborating, and allows you to promote only the best version of your code to higher environments.
A very important part of the Git workflow is creating pull requests, or PR in short. As a consultant, I have worked with multiple clients of varying technical maturity, and I have observed that writing beautiful PRs is an art in itself. Your PR is like a story, and a story is best told when it has the why, how and what answered, along with other essential pieces. It allows you to explain the reason for your code changes, how it can be implemented according to your reasoning, and what code changes have been made to justify your “why” and “how”. Your team can only give you proper feedback if they understand what’s being fixed or enhanced, and not many people are good at writing great PRs.
I am not an expert at this by any means, but I have seen a lot of PRs in my career, and I strive to improve every time. Some of them I’m in awe of, and some of them are not worthy of review. However, I do believe that good PRs are a necessity for a well-functioning tech and data team at any organisation. In this post, I want to share some of the best practices I have seen and some of the worst practices you should avoid.
And for people who believe writing PRs is not important, it's the code changes that matter, I don’t think this article is right for you, and I hope we don’t ever work together.
Commits are breadcrumbs.
Commits are the building blocks that make up a PR, and they can be considered scenes in a play or a movie. When thinking about a scene in a movie, you think about that moment. Similarly, a commit should tell the story of a piece of work. It should have a meaningful change closely related to that piece of work and should create a timeline of your progress when your work is complete. A general rule of thumb is to commit every 3–5 related code changes. The goal of a commit should be clear to the reviewer as they connect the dots to explain the “what”.
Why are commit messages important?
- When your teammates review your code or when an employer looks through your project, they will look through your commit history. Having a good commit history will show them your thinking process and help you stand out.
- Commit messages and history are helpful in identifying bugs and flaws in the understanding requirements.
- Good commit messages can also act as a time travel machine. If you’ve stepped away from a project for a while and are returning to it, you likely won’t remember the thought processes and nitty-gritty details when initially writing the code. Commit messages can help you here.
Bad vs Good Commits
Imagine reading through a commit history that looks like this ‼️
It is impossible to know what the code changes are for by reading these commit messages unless you look into the code yourself. The commit messages are too vague, and it will leave you confused.
Wait, there are some funny ones, too.
A good commit message is one where developers can gain a better understanding of the code change without having to look at the code. It should:
- Specify the action of your code in the subject line.
- Have a clear and concise description of why the commit is required.
- A blank line between the subject line and the body to separate them provides better readability.
Now, let’s write a good commit message keeping the above in mind.
Add a missing call to action button next to the newsletter banner.
Readers will not be able to subscribe or create an account without this buttonAh, that’s better.
Tips and things to remember:
- Use a code editor like VSCode to make multi-line commit messages.
- Use active voice
- Avoid vague commit messages like “fixed” or “update”.
- Commit early and often!
- GitHub has a 72-character limit so don’t make your commit messages too long.
If you’re not part of our community yet, I would highly encourage you to be part of this growing vibrant community who is disrupting the status quo and making the tech and data space a better space. Plus you get access to tons of exclusive free, never to be found anywhere else, high quality resources which you can use to boost your productivity. It’s free and it hardly takes a few seconds. I promise I don’t spam and you can unsubscribe anytime.
Minimal number of file changes in your PR
If your PR has too many files changed, something that requires your teammates to grab a cup of coffee or need another pair of eyes to review them, chances are that your PR is too large, and there is room for improvement. Yes, there are exceptions to this, but the general rule of thumb I would follow is, if I am the reviewer, would I review this on a Friday afternoon, or would I push it to Monday? It’s a lot to digest if there are more than 20 files changed, and the reviewer needs to put in so much cognitive load and focus to review the changes.
In such cases, you can try splitting up your PRs based on related code changes. For example, if you’re working on a data project, you can create PRs for
- Upstream changes
- Downstream changes
- Main logic changes, documentation, and tests
If you’re working on a tech project, you can create PRs for:
- Frontend changes and tests
- Middleware changes and tests
- Backend changes and tests
- Database migration changes
- Any documentation updates
Tips and things to remember:
- If you think your PR is getting too large, it probably is.
- Check your commits for unexpected files or files that don’t need to be reviewed and are present in your PR, such as node_modules or external packages; these can reduce the number of files changed.
The Great PR Description
A great PR description can answer most of the reviewers' doubts and questions, making their job much easier and speeding up the review process. A great PR description should contain the key questions answered which we discussed earlier:
- Why are these changes required? Provide context to the reviewer and provide reasons for making this change.
- How can this change be implemented? Provide high-level thinking and the general approach taken to implement the change.
- What changes did you make? This can be a bullet list of changes to the individual components/systems.
Even better, you can now automate the entire flow. All you need to do is create a reusable PR template in your Github Repo. This way, you can never write bad PR descriptions anymore.
In my career, I have seen some great PRs; some include GIFs or memes to lighten the mood of reviewers, some include external links and references, and some include pictures and emojis, as a picture can tell a thousand words.
Read more about creating PR templates here. And for our exclusive community members, you get access to the internet’s best curation of PR templates here.
Writing great PRs is an underrated productivity hack. Good PRs can move work, and great PRs can evolve your team and codebase. It not only helps you, it uplifts the entire team.
Thank you so much for reading!
Sanjay.
WordCloud for Productivity and Self-Improvement
software engineer, computer science, programming languages, software engineers, technical knowledge, technology plays, new technologies, learning HTML, technology, code, knowledge, create, technologies, users, systems, tools, development, world, developers, communication, computers, data, future, process, software, creating, access, computing, device, computer, site, skills, progress, life, branch, engineers, security, methods, school, range, online, support, students, program, technical, education, person, infrastructure, creation, business, environment, robotics, maintain, skill, request, databases, organization, innovation, develop, interests, functions, forms, tool, companies, database, innovations, employment, ideas, customers, website, introduction, examples, tasks, form, feature, search, analysis, collaboration, visit, communicate
