Ask anyone in the DevOps community and chances are, they will tell you that code review is time-consuming and frequently boring, but it’s a critical phase of the software development process. What they mention less often is that the long back and forths with developers can be spared if you first get your commits right. We suggest 5 practical techniques to make code reviews more efficient by improving your source code change management practice.
Why should you care?
The intent of any change in a software project has to be clear during its full lifetime, even after many merges, many years after their creation, and many code owners transferred among. Maintaining a traceable commit log may not sound very important, but think about safety critical domains like medical systems, aviation, or nuclear energy. If something goes wrong in their line of business and they have to face audit scrutiny or post-mortem analysis, the change history of the affected systems’ source code needs to be precisely verifiable and traceable.
What if you had the same level of control and same quality of source code as for a lunar landing system?
What makes a good source code change?
Before improving the code management practice, some general characteristics of a “good commit” should be established. Linus Torvalds, the father of Linux and inventor of Git, has some very clear views on what a good commit looks like (some apply to Git only, but others are also applicable to Subversion, Mercurial, etc.).
TL;DR, here are the generally accepted recommendations:
-
Committer identity is clear
- A good commit is encrypted and signed so the author’s identity can be confirmed. It makes permission-based code changes possible and prevents any tampering with submitted commits.
-
Commit message is useful
- The first line should be a summary of changes in about 50 characters, leave the second line blank and wrap the body text at 72 characters, so it's nicely readable instead of a giant one-liner. (Hence the 50/72 rule in Git.)
- Write mostly about the "what" and the “why” and not about the "how".
- Use the imperative, present tense. (“Add company logo” instead of “added company logo”.)
-
Only the relevant files are changed
- In certain repositories, only pre-defined files or files types are expected to change. A good commit never adds, removes, or modifies files that it is not supposed to.
-
Committed to the right branch
- There is a well-defined branching strategy established and commits are made against the branch they logically belong to.
Now let's add to that list a few more that get emphasized less often:
- Link the commit to the issue that triggered it
- If you are using an issue tracker, service desk, agile board, requirements management system, or any sort of project management tool to manage your work items (who doesn’t?), make sure that the commit has a solid reference to the issue, ticket, user story, requirement that triggered the change.
- It's OK to write a commit message longer than the commit itself
- Tiny-looking changes can be a conclusion of a long decision making process or can have wide impact on the whole, so make sure you explain them just like big diffs.
- Use consistent and precise terminology
- Don’t use multiple words for the same technical notion or domain entity or feature. Avoid synonyms unless you have a good reason not to.
- No nerdy details
- The commit message is not the place to make yourself shine and explain your engineering talents. Keep your language simple and to the point.
- Use your manners
- Always assume that your commit message will be read by someone with a different cultural background, and use appropriate language.
Fire up your source code management system
The following five techniques are actionable suggestions for DevOps teams. These are intended to help establish a disciplined source code management practice, regardless if you are starting fresh or working with a legacy system.
1. Empower your team
When DevOps teams introduce new commit standards to their projects, it’s important that they keep those friendly and human, otherwise the adoption will be slow, partial, or frustrating. There are powerful apps available on the Atlassian Marketplace that help enforce commit policies. However, setting up some rules and having an app enforce those on developers doesn't sound like teamwork.
The successful introduction of company-wide commit policies also requires preparation and communication with developers, allowing them to express their concerns and ask their questions. Using the internal knowledge base and communication channels to distribute best practices and address concerns will make the whole project transparent and not another pointless policy that comes “from above”.
2. Tie commit rules to project requirements
Commit rules that are aligned with project requirements and with the team's work methods are more straightforward and make the purpose of the whole commit policy more comprehensible for the team.
A few typical commit policy examples to give you an idea:
- Accept GPG signed commits only
- Accept commits only from developers who are members of certain Jira groups
- Require commit messages to begin with a Jira issue key, tracing changes back to the issues that triggered them
- Accept only commits that reference an "In progress" Jira issue of the Story type, assigned to the committer
- Require branches to follow a predefined naming convention
- Only accept .html, .js, .css, etc. files in a web development project
3. Catch non-compliant commits as early as possible
Getting used to the new commit rules is a learning curve, but mistakes, like wrong targeted branches or forgetting the issue link, can happen regardless. The earlier those errors are detected, the easier it is to fix them.
For centralized version control systems, you can detect those immediately when the developer commits.
For distributed version control systems, most tools process commits only when those are pushed to the server-side repositories. At that point it’s too late: if the developer pushes several changes in one go after a productive work day, this is extremely frustrating to fix the rejected ones that he made some hours before. (Rewriting commits can even be dangerous if those were already published to some other repository in the meanwhile!)
Make sure that the tool you are using verifies the commits in the developer’s local repository.
4. Offer meaningful rejection message
The rejection message is a short explanation for the developers when their submitted code changes are not accepted to the central repository due to a commit policy breach. It is often the developer’s first (frustrating) encounter with a commit rule. Make sure your rejection message doesn't leave the committer in doubt and instructs them precisely what is expected in that repository. Instead of long explanations, it is more efficient to show an example commit message that would be accepted.
5. Collect feedback
Once the policy is in place, get feedback from your team, and continuously improve the commit rules based on those. If you are already using the Project Team Health Monitor framework, make this review part of it. The goal is to make contributors see the commit policy as their assistance in keeping a precise change log, maintaining code quality, and helping their code reviews, and no one feels that they are over regulated arbitrarily.
How to get started?
To create and maintain exceptional source code change management standards in your organization, you need a VCS agnostic tool on your side. Better Commit Policy for Jira allows you to create parametric conditions in Jira and verify changes committed to your repositories against those. It integrates with all major version control systems out of the box and offers a clean REST API for the others. It helps introduce commit standards, which fundamentally improve the quality of the software team's work and makes traceability default for all your software projects.
Create your first commit policy!
This blog post is also published in the Atlassian Blog.