This is a guest blog post by Atlassian Marketplace vendor, Midori.
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.
Fresh ideas, announcements, and inspiration for your team, delivered weekly.Subscribe now
Why should you care?
The intent of any change in a software project has to be clear during its full lifetime, even after many years and merges. 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 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.).
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, or any sort of project management tool, make sure that the commit has a solid reference to the work item that triggered the change.
It’s OK to write a commit message longer than the commit itself
Tiny-looking changes can have a 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.
Use your manners
Assume that your commit message will be read by someone with a different cultural background or sensitivity and use appropriate language.
Give your team control over source code changes
When DevOps teams introduce new commit standards to their projects, it’s important that they keep those tied to the project requirements.
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
An advanced feature that assures code reviews are streamlined is catching non-compliant commits as early as possible. For centralized version control systems, you can detect these immediately when the developer commits. For distributed version control systems, the earliest you can verify changes is when the developer commits locally. 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, this is extremely frustrating to fix only the rejected ones.
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.