Tag Archives: Git

Git Basics: Pull Requests

By Agustin Aliaga – Developer at Santex

Git is a powerful version-control system designed to make software development collaboration easy. It can be used for personal (single contributor) repositories, but it really stands out in projects where multiple developers modify the same codebase every day. Multiple branching models can be adopted. However, in most cases, a Pull Request (PR) will be created when a bug fix or a new feature is ready to be merged into the main branch. The PR itself is an attempt to merge specific changes from one branch to another. Let’s explore the Pull Request workflow in detail.

PR Creation

Whenever a PR is created, the following good practices should be considered:

  • Adding a helpful description to the PR that answers the following questions: What is the requirement or bug? Is there a link to the issue (e.g. on JIRA)? How does your code fix it? Is there anything else the reviewer should take into consideration?
  • Making small, consistent and logical PRs: We want our PR to be merged as soon as possible. Imagine how hard it would be to review hundreds of file changes at the same time. If this happens, it is likely that the reviewer won’t even have the time to do it properly. So try to keep it simple and concise.
  • Making sure the PR’s metadata has been set. For example, by assigning the reviewer (to trigger a notification), setting the assignees, adding a label (if needed), etc.
  • Configuring the repo’s branching security settings to keep developers away from self-merging their PRs or pushing to a shared base branch. I recommend enforcing Github’s branching security settings. When a large team of devs is collaborating in the same repo, accidents may happen. A single miss click in a “merge” button can cause terrible headaches. Protecting important branches is something I’d advise most of the times.
  • Avoiding submissions that include unresolved conflicts. Fixing those conflicts shouldn’t be a reviewer’s responsibility. PR creators should dedicate time to solve them either by using Github’s conflict resolution tool (when it’s simple enough) or by using your favorite diff tool locally. You can achieve this by pulling the base branch and merging it into your feature branch. After you pushed it to the remote repo, the PR will automatically update.

Automated tests

If a Continuous Integration system (such as Jenkins, Travis, or CircleCI) is set up, a bunch of hooks can be configured to run unit tests on PR creation. This will allow the team to detect and catch bugs rapidly, as well as prevent conflictive code from being merged. This is a long topic that requires its own blog post, so I’ll just move on to the following stages.

Code Review

After everything related to the creation of the PR is dealt with and the CI tests passed, it is time for a code review. Projects tend to have tight deadlines, which sometimes makes code reviews seem like a waste of time by other team members or external agents. Ironically, code revisions actually help to increase productivity and reduce rework because we avoid bad practices in our code and share knowledge between contributors.

Some benefits of implementing code reviews are:

  • Less experienced devs get to learn from their mistakes.
  • Experienced developers consolidate their knowledge as they teach others.
  • A high-quality codebase is ensured.

Humility: a soft skill that matters

Sometimes, as work starts to accumulate and things get tense, some engineers tend to become less aware of their attitude towards their peers. It is always important to avoid egocentric behavior, listen to our co-workers, and moderate our communication when reviewing other people’s work. If we write a PR review in a disrespectful/arrogant manner, we could be damaging the team’s confidence and the work environment.

The “reviewer” role

Ideally, teams should implement peer reviews. This means that anyone should have the required experience and skills to review other’s code. In practice, collaborators regularly have different levels of experience on both the technology used for the project and the codebase itself, including its set-up, architecture, code styling, deployment, etc. In this case, experienced developers should be conducting the reviews and newer team members should be included progressively as they get comfortable with the project.

Merging the PR

After the PR was approved, it’s time to merge it. We have a couple of options to do so. Let’s explore them:

  • Create a Merge Commit (default): This option will merge all the commits from the feature branch plus a new merge commit. This is the safest way to perform the merge, since it is a “non-destructive” operation. The downside of using this option is that since it creates a merge commit to tying together the history of both branches, it pollutes your history tree with multiple “irrelevant commits”.
  • Squash and Merge: This option will “squash” all the commits into a single one. If the PR includes a lot of commits, this could be the way to go. It will make your history tree much cleaner and easier to read in your base branch. Nevertheless, you will lose granularity due to the bigger size of the resulting commit.
  • Rebase and Merge: The “rebase” operation is another way to combine commits from two different branches. This will put your feature branch commits on top of your base branch’s latest commit, and effectively rewrite the commit history. After this, it will perform a fast-forward merge, making it look like all the work was done on the base branch. This is extremely dangerous when the rewritten branch is public and shared with other team members. Generally, the rule of thumb is to keep rebasing operations for private-only branches.



Good committing

By Jose Torres – iOS Developer at Santex

People in software development know there are a ton of difficulties a team faces when working on software projects. That’s why best practices were introduced as a way of preventing  common problems that software teams eventually face. Best practices cover many aspects, from the environment setup to the way we write code and produce deliverables. Unfortunately, one aspect usually forgotten or underestimated is the handle of the repository. This usually happens when the team is small – if you are the only member on the team, you are prone to get disorganized. This can dangerously hide other potential issues usually faced when the team grows and you find yourself in complicated situations or flows. As the team increases its size, a lack of good practices will reveal itself and problems will surface.

As engineers, we should understand the importance of doing things right. It shouldn’t matter that our current context shields us from facing complex situations. We have to be prepared for when the context changes and things start to scale. It happens often that engineers have this feeling of “things are working fine,” so therefore the context is “that should mean we are doing things well,right?” Not facing issues in the moment is not a guarantee that things are being done right.

There are many areas of good practices surrounding Software Configuration Management. Let’s focus on some of the best practices when committing code.

When committing code, we are introducing new code changes to our code base. In distributed version control systems, this is done first in our local repository and then the code is applied (“pushed”) to the central repository. There are multiple approaches on how to handle the branching model of a repository, but we will focus only about the committing. It is basically a general rule that a commit in code should reflect an atomic change. This means that it can only be applied entirely, never partially. And, of course, it should not break the build. All build routines and tests should run successfully.

When committing code, we also have to include a commit message. This message is meant to give more information about the code changes that have been introduced. Such a message will last through eternity, and it is our duty to use it wisely.

Image 1: Sample git log

Limit your commit first line (title) up to 50 characters

This is one of the most common suggestions, but it is still forgotten. The first line is treated as the title of the commit. This means it should be brief and concise. It must be no longer than 50 characters, and ideally should not be too short either. This characters length may not be a hard limit, but having it in mind ensures that the author thinks for a moment on how to concisely describe the commit. This helps to get quick contextual information when navigating through the git history and ensures that all clients will display the commit info properly.

Consider a blank line before the description

In order for Git to differentiate the title from the body of a commit, a blank line must be added. Of course, this is only required if we want to add a description. Whether a description is needed or not is up to the author. However, it is a good practice to include a description that adds an explanation of the changes introduced and also some contextual information, like a related ticket number or link.

Include a link related to the issue on Bitbucket/GitHub/JIRA/etc

This is related to the previous suggestion. It is important to have a reference to the source of the request, so we can have more context of the change overall. This should not be part of the title of the commit, but rather part of the description with the full link. If it is a bug fix, requirement, enhancement, etc., most of these are tracked with software development tools that assign them a unique identifier which makes it easier to track development. On one hand, it helps each commit in the repository to have a full reference. On the other hand, it gives visibility to external tools about when, by whom and in which branches the changes are applied.

Write the message using present tense/imperative mode

Finally, the golden rule of committing: all the writing must be done using an imperative mode like [FIX] and not using past tense like [FIXED].

Define a template

Having all of the previous considerations in mind, the team should define a template. After discussing what should be included in the ticket as the description and syntax of the titles, your team will have a clear idea of how they should commit code. Here is a sample I use for my current project:

Image 2: Sample of a git commit structure

All of these good practices will be useful in many situations that software teams often face.

Help during the review process

When doing code reviews, we have to check all of the new code that is introduced. Having a clean commit history with descriptive titles and useful messages helps to understand the reason behind the changes. Also, as the reviewer will have access to the description with a link to an external tool, he/she is able to understand the full context of the change.

Help when handling merge/rebase operations

This is my favorite. Every time we have to deal with rebase operations it is extremely useful to have a clean commit history. This helps to make sure you are moving the right code changes from one branch to another. Without this information, it will be almost impossible to do without having assistance from the original author, which as we know may be impossible sometimes.

Help when writing release notes

At the moment of preparing the release notes, a clean commit history is useful so we can see all changes that are part of our release branch (or any branch we are using to prepare a release).

Help during maintenance

Finally, one of the most important reasons for having a clean commit history is so that we can understand changes that were introduced a long time ago. Often as software engineers, we are in a situation of not understanding why a specific change was made or why a piece of code was originally introduced. A well written commit will bring together all of this information, and will give important insight for the new authors to avoid having side effects when performing a change.

Image 3: Sample of a rebase operation for moving code between branches

There are really a ton of recommendations and conventions for good committing. These were just some of them! These are the ones I think are the most basic and need-to-know, and are based on the official Git Man page1.

Let me know if you have any others you would like to add or suggest.


– [1] https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-commit.html#_discussion