5. Writing Meaningful Commit Messages

Why is Important?

According to Hombergs[2]:

Commit messages are a way of communication between team members. Let’s say there’s a bug in the application, to find out what caused the problem, reading the commit messages could be handy. The proper commit message can save a great deal of time finding the recent changes related to a bug. If we fix a bug or add a feature we will probably completely forget about it a month or two later. It’s not a good idea to think that if it’s not clear for others, they can ask us about it. Instead, we should provide proper commit messages for people to use as a resource in their daily work.

How to write good messages?

Which verb tense to use? Should be capitlazed or not? These questions are always upon debate. But in essence, a commit message should have the following characteristics according to [1]:

• It should be understandable even by seeing only the header of the message
• It should be just enough, and not too detailed.
• It should be unambiguous.

Let's see some examples:

(Bad)
update readme.md

(Good)
docs: correct spelling of README.md

The Simple and Generic structure for a Good Commit

In this project, we are following the conventional commit message approach. This approach is suitable for a beginner because is easy to follow the guidelines. The conventional commit message structure:

prefix(optional scope): description

optional body

optional footer(s)

As an example a commit that introduces a new feature:

feat: allow ml model to be trained on a different dataset

If you perform an isolated modification in the documentation, fixing a typo in a python's script docstrings or creating an example, you should use the docs prefix.

docs: correct spelling on the docstrings

But don't be afraid of using the "wrong" prefix, it's ok to choose what you believe is more suitable for your case.

Adding scope to commits.

You can get a step further and use scope. The scope is a way to be more specific about what you are doing and can be used to organize a group of commits. Let's take a look at the following example.

fix(model): remove the dependency on the sklearn library

The Sklearn is incompatible with the model, thus the dependency is being removed.

How to draw attention to a specific commit?

Suppose you sent a pull-request containing several commits. How to communicate to reviewers that some commits should be carefully reviewed? That they need to read the entire message? One way to do this is to use the exclamation mark !.

Let's see an example

fix!: remove pip 22.0.2 dependency

Changes present in this commit must be removed
after `pip-tools` team's solution regarding pip log bug 
be merged and released

Related to: https://github.com/jazzband/pip-tools/issues/1558

Let's take a look at another example

feat(model)!: implement a new model more efficiently


BREAKING CHANGE: This model can result in a **critical** performance loss
if the dataset is not well-represented. 

Table of Prefixes & Descriptions

The tables above have the prefixes and the corresponding descriptions. In the future, as necessary for the MLOps Project, we will add more prefixes.

This is the first table that is common to all Software Development Teams [2, 3]

Prefix	Title	Description
feat	Features	A new feature
fix	Bug Fixes	A bug Fix
docs	Documentation	Documentation only changes
style	Styles	Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
refactor	Code Refactoring	A code change that neither fixes a bug nor adds a feature
perf	Performance Improvements	A code change that improves performance
test	Tests	Adding missing tests or correcting existing tests
build	Builds	Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
ci	Continuous Integrations	Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
chore	Chores	Other changes that don't modify src or test files
revert	Reverts	Reverts a previous commit

The next table represents to us our current understanding of which prefixes (commit types) should be incorporated in the previous table to improve the quality of code evolution in MlOps projects.

Commit Type	Title	Description
model	ML Model	Changes and/or create a ML model
eda	Exploratory data analysis
data	Data
report	Report

References

[1] “Conventional Commits.” https://www.conventionalcommits.org/en/v1.0.0/

[2] T. Hombergs, “Writing Meaningful Commit Messages,” Feb. 22, 2021. https://reflectoring.io/meaningful-commit-messages/

[3] “Editing conventional-commit-types/README.md at master · pvdlg/conventional-commit-types,” GitHub. https://github.com/pvdlg/conventional-commit-types