Creating a robust pull request

Photo by Annie Spratt on Unsplash

I used to not like review processes which slowed down my PRs to get merged and deployed to production. I remember my then CTO, Arzumy MD, during a catch-up, commenting about this issue and he guided me to understand the reason why we have to go the extra mile in the PRs we create. Some pointers that I remember were:

• PRs are globally available for everyone(in the tech team), so you can read other senior engineer’s PRs, see how and why they write what line of code.
• Your PR would also be available to everyone, make it as self-documented as possible so that it can be informative for yourself and your peers later in case of any mishaps.
• You should be able to use your PR to help yourself(present and future) and your fellow teammates who will review your code, provide as much context of what work you did.

A small catch up like that left a huge impact on my tech career so far and how I look at code/pull requests as I look at my PRs like a product in itself and it is my responsibility to make sure that it works “as it should” and that it has the observability to validate that it is working with the PRs of past and the future(enter specs, but we shall talk about that some other time).

So I will be explaining and going through the details of how I personally go through each ticket assigned to me by anyone. This is all my personal opinion, so it might or might not work for you, I leave the judgment up to you and how your company does software engineering processes. We are mostly gonna focus on the PR aspect, not the code.

Commits

I am a firm believer in not creating lots of commits for a PR. Usually, the belief is to create as much commit as you can, but it makes retracing code really difficult, and git blame/git lense is not helpful to backtrack. I use git reflog to check my progress and I keep one major feature limited to one commit.
I also use git rebase -i quite a lot to manage my commits, so you can commit all you want and later squash it.
If there are more commits needed I always label the initials of the commit with the ticket number. For eg. MANGO-245 , where MANGO is the name of your team/jira board and 245 is the ticket number.

• helps track commits in the commit history.
• when services like datadog or sentry.io trace back exceptions and errors you can pinpoint exactly which line the issue is in and in which PR did it get merged and deployed.
• once you have a minimal commit message with information like that, it is gold to help debug where what went wrong.
• helps hotfixes as you can cherry-pick one entire feature off of a branch if need be or remove it 🤷‍♂.

Branching in git is another mystery. It can be simply complicated. What makes it tough is where to branch out from and where to point it to. Special care needs to be taken in that regard. Mostly it is better to use some kind of a tool for git like sourcetree, but I use a combined approach of command line and gui based solutions ← this is only when things are super-complex AKA your entire company uses one single schema file and you only want your changes to show up in your PR. This brings me to:

Git part

This is one of the most crucial parts, but we get so accustomed to it that we don't think about it. I want to point out my usual flow on things and then some edge cases.

New feature request

$ git checkout develop  //assuming a 'main'/'develop' approach
$ git pull              // to pull all the latest changes
$ git checkout -b "feature/MANGO-245-describe-the-ticket"
-- do moi werk --
$ git commit -m "MANGO-245 describe the commit"
$ git push origin head

In case I need to make a not so major change, I would not create another commit… After -- do moi werk again -- , I would:

$ git pull origin <target-branch> --rebase
$ git commit --amend --no-edit

The --no-edit flag lets you have the same commit message.
I would implore you to check out git commands like:

$ git reflog
$ git rebase -i
$ git reset (--hard | --soft)

These are all I can think of from an everyday perspective. For any git f*** up, git has an amazing blog that you might wanna check out.

While you wave your git power in the face of adversity, please keep check on the progress of your target branch of your PR.

Use $ git diff feature/MANGO-245-your-ticket...develop , to check for growing differences which have a habit of notoriously increasing over every second sometimes.

Comment your flow out and I shall add it to the blog. Or maybe we can create a repository with git-flows IDK, I’m open to ideas 😃.

Now that we are almost done with the logic and git stuff, we have to think about what we are gonna do if our PR creates a massive downtime in the company because of which we lose BILLIONS of dollars and every in the world dies… only cz of our PR . * sips coffee * Probably not but you know, you never know… Anyway

Pull request templates

I love a good PR template that makes a PR a joy to review. Apart from the fact that keeping the PR as small as possible should be a high priority, PR templates really help reviewers get a context of what sort of work has been done. Since context switching is one of the hardest tasks to do, we must assist our reviewers with enough context so that it does not add to their cognitive complexity.

Github Templates: The Smarter Way to Formalize Pull Requests Among Development Teams

Gonna link a very nice read published in https://betterprogramming.pub/.

The main goal is always asking yourself, how we can help reduce some tension on the human aspect of our non-humane endeavors by just aiding with some context.

Side note: These detailed PR templates can help you explain what changes you did and why(Psst… Blame is on MANGO-245 , classic 😉).

All in all, these are the few things I personally do in each and every PR. I sincerely hope that it helps you in managing your work more efficiently and to save you some anxiety, because we all have enough on our respective plates, as it is…