Making git commit messages useful with Jira, Jenkins and scopes

Writing anything meaningful in the commit messages already makes you an awesome dev and puts you ahead of most. I've seen too many meaningless commit messages and it makes it so hard to track down a problem. Some of the most famous ones I've read were:

• WIP: Keeping it in your branch is ok, but whenever creating the PR it has to be cleaned up a bit. An interactive rebase might be really useful.
• fix crash, tweaks or more refactoring: these ones are famous for two reasons: happens a lot and never explains what was the change.
• Navigating down in the search result set eventually loses focus completely (cannot navigate) or jumps focus to keyboard: reading stories like these in git messages is a bit harder than it might seem. It doesn't really tell anything about what was done but instead focuses on the problem.
• .: yes, it's a dot! And trust me, I've seen this. It it wasn't done with a bad intention, I know. This kind of commit can easily get in main branch if someone adds some fixes after the PR was created, and then the PR gets merged using the Merge Request or Rebase and Merge from GitHub.
• Merge pull request #3904 from user/bug/branch-name: Having these in the main branch for every PR messes things up a lot. The problem here is that both the commits from that branch (like missed import or final fixes) come in together with one more merge pull request commit which makes it so hard to understand where it starts/ends. And besides, it doesn't really give any valuable information.
• ticket-number: It does help to track down and read more about the change. But it still makes it very hard to skim through commit messages in git history when looking for specific scope/area changes.

Upon seeing these issues, I've written down some guidelines on how to get more out of commit messages where Jira and Jenkins come into play as well.

The Commit Message Format

Each commit message must follow a special format that includes a ticket ID, a scope and a subject:

<ticket-id>(<scope>):<subject>

Any line of the commit message title should not be longer than 72 characters. This allows the message to be fully visible in one line on GitHub as well as in various git tools. If you need more than 72 characters, leave an empty line and continue adding more details.

While writing the description, also try to limit to 72 characters per line, so that it looks properly in various git tools as well.

TIP: I'm a CLI guy, but if you are using SourceTree you can add a margin line at 72 characters by going to Preferences → Commit → Use fixed-width font for commit messages and Preferences → Commit → Display column guide in commit message at character.

The ticket-id

Ticket ID contains the ticket number this commit is related to.

• If commit is not related to any ticket, then either create it, or skip writing the ticket number. Though it is highly encouraged to opt for creating one.
• Avoid having more than one ticket per commit (there are exceptions though).

The scope

The scope could be anything specifying place/area of the commit change.

For example: player, mixpanel, gradle, home, feed, settings, ad, etc.

• use * when the change affects more than a single scope.
• don't write a too specific scope like player-controls, menu-icons etc. nor too generic like icons, animations, list etc.
• tend to use only one word, but if you have to use two words, then use the camelCase notation
• don't use spaces

The subject

The subject contains succinct description of the change:

• Must complete the following phrase: If applied, this commit will
• use the imperative, present tense: change not changed nor changes
• don't capitalize first letter
• don't capitalize letters unless very necessary
• no dot (.) at the end
• no space at the beginning of subject
• try to avoid generic words like ProjectName or current platform/framework which are obvious and do not add necessary information to a commit message.
• if too many things have changed and cannot be summarized on a short message, please use git add -p
• tend not to use generic words like fix the player, which doesn't give any information on what was changed. Be specific on what exactly fixed the problem; for example: access videoControls instance safely inside viewModel

The information in subject

• Describe why a change is being made.
• How does it address the issue?
• What effects does the change have?
• Do not assume the reviewer understands what the original problem was.
• Do not assume the code is self-evident/self-documenting.
• Read the commit message to see if it hints at improved code structure.
• The first commit line is the most important.
• Do not write stories in multiple lines explaining why something is necessary, we have tickets for that; so don't go too specific. Try to be succinct but straight to the point.
• Never mention multiple tickets per commit. Exceptions may be the case when exactly same modification applies to more than one ticket.

Commit message examples

• ticket(carousel):pause timer when carousel is not visible
• ticket(carousel):report to analytics when slider is visible
• ticket(player):safely pause the controller
• ticket(show):add the missing shadow to show tiles for tablets

So how does it all come into play together with Jira and jenkins?

• whenever a PR is created in GitHub, the mentioned ticket is transitioned in Jira to PR Ready
• in Jira's ticket, one can see the reference to all PRs and commits for current ticket.
• whenever delivering builds, Jenkins will create a changelog based on the diff between last built commit and current commit. It will have references to both Jira tickets and GitHub commit for every commit. This is a very useful changelog for developers, QA and product.
• ticket scope helps quickly skim through commits to find a related bug

Taking it to a next level

There is this amazing tool called Commitizen which helps formatting the commit messages using the usual git CLI interface. I haven't used that yet, but let me know if anyone did and if it was helpful.

Question: What guidelines do you guys follow in your projects? And how strictly do you follow those?

Feedback is very much appreciated.

Thank you!

Note:
I've read multiple guidelines from different open source projects so if you see anything that was mentioned somewhere else, it means I really liked it. Especially the JavaScript commit guidelines which have a very well defined structure

References:

• https://chris.beams.io/posts/git-commit/
• https://github.com/apache/griffin/blob/master/CONTRIBUTING.md
• https://gist.github.com/stephenparish/9941e89d80e2bc58a153

Comments

[Sergey Kislyakov]

I find conventional commits a bit better. We have applied this approach in our team and it's much easier to understand what's going on it the codebase just by reading commits. It also helps a bit when we're preparing a plan for demonstrating our changes to other teams (along with the issues).

<type>(<scope>): <subject>

<body>

<footer>

Your JIRA/GitHub/GitLab/etc. issue would be in the footer section maybe with an automating tag (Fix/Close).

[Filip Luchianenco]

Thank you for your input Defman. We actually tried to follow exactly this format initially, but then we felt like the ticket number is something we use a lot on all levels, so we need it up there. Using the ticket, type, and scope leaves so little space for the subject, so we had to take something out, which was the type.