By Jose Torres – iOS Developer at Santex
People in software development know there are a ton of difficulties that a team can face when working on software projects. That’s why best practices were introduced: as a way of preventing common problems that software teams will eventually face. Best practices cover many aspects, from the setup of the environment to the way we write code and produce deliverables. Unfortunately, one aspect that is usually forgotten or underestimated is the handling of the repository. This usually happens when the team is small – if you are the only member on the team, you are bound to be disorganized. This can hide other potential issues that are usually faced when the team grows and you find yourself in complicated situations or flows. As the team increases its size, a lack of best practices will reveal itself and problems will surface.
As engineers, we should understand the importance of doing things right from the beginning. 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 often happens 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 best practices surrounding Software Configuration Management. Let’s focus on some of the best practices that should be used 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 to handling the branching model of a repository, but we will focus only on 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) to 50 characters
This is one of the most common suggestions, but it is still often 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. On the flip side, it should not be too short. The character 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 a 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 used for my current project:
Image 2: Sample of a git commit structure
All of these best practices will be useful in many of the 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 has been introduced. Having a clean commit history with descriptive titles and useful messages helps us 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 would be almost impossible to do without having assistance from the original author, which we know may be impossible sometimes.
Help when writing release notes
When 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 the changes that were introduced a long time ago. Often as software engineers, we are often 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 to the new authors, allowing them to avoid having side effects when performing a change.
Image 3: Sample of a rebase operation for moving code between branches
There are 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.
Links:
– [1] https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-commit.html#_discussion
