Conventional Commits as a more robust and informative system for describing code base changes

[olayway]

I feel like our current system for describing changes in our codebases doesn't yield very informative commit messages and commit history.

Situation (current system)

This is the structure of commit messages we currently use:

[<files changed>][<change size>]: <description>

<optional body>

Complications

1. Files changed

• Impractical for commits involving many files, especially across different directories (which is very often the case).
• It duplicates information that is already present in the commit diff.
• (opinion) I never even look at it, because 1. I know how awkward it is to add this information in the first place 2. This is never the information I'm looking for when looking at the commit history. When I'm looking at the commit history, I'm mostly looking for a why. Why a given change was made, by whom and (would be nice) what type of change it is - is it a bug fix, a new feature, a docs change?

2. Change size

• very subjective and varies significantly from one developer to another
  • "Is it size in terms of how many lines of code were changed or in terms of the impact of the changes?"
  • "How big is this size compared to... what?"
• (opinion) I have never looked at this field, neither in my commits nor in other devs' commits, because of how subjective it is. I'm using it because this is our convention but it always feels awkward to add it and even across my commits I know the sizes I'm using are super inconsistent.

Where is the "why"? Why this change was even made? Is it a bug fix, a new feature, docs, or CI-related change?

Solution

Use Conventional Commits specification instead, with the following commit message structure:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

[olayway]

@rufuspollock, @demenech, @lucasmbispo, @khalilcodes, @anuveyatsu Would love to hear your opinion on this!

[demenech]

+1 for this

That sounds like a good approach, I bookmarked it.

[rufuspollock]

@olayway i'm happy with the proposed change. Note already i use the first segment to indicate the area (not just the specific areas changed) e.g.

[api][l]: refactored api substantially to do X Y Z

For me the one thing is I do like the size indicator e.g. [xs] etc as i find it useful when grepping or getting an eyeball on substance of other changes. However it can be a bit subjective.

Overall happy to go with ola recommendations.