Fried egg

Follow two simple rules for a readable and consistent codebase history. The rest is personal preference. Like this fried egg.

I was just trying to find out if a certain feature made it to our app’s latest release.
Headed to Github, master branch, commits.

Reassuringly, sitting at the top was our latest merge commit from the pre-production branch, followed by a list of short commit titles.

— This is gonna be an easy task 🙂

Right below, another PR merged, and then:

145ce493 Uncomment lastImportDate at the end of contacts loop

That was not it, keep sweeping down.

b1156846 Analytics: track app upgrade event

And then this:

3075e1f4 hope this time it works
8c213812 Fix
8c624d9c New notification maybe finished
eb98f77b PR comments from Sandra
008f2279 fix for weird stuff
98274dba I forgot something

😐

How can I possibly know what happened there without going into every single commit’s changes?

This is very common across development teams and, fortunately, very easy to avoid.

 

All we need is love

A good team is greater than the sum of its parts. That’s synergy.

Applied to software development teams, it means that to be part of Team Kick Ass, I don’t need to be an expert on Automated QA tools, and Analytics, and React, and CD/CI, and node, and SQL at the same time.

Or know how the next person sweeping through our code history likes their commits.

I basically need to kick ass at my own area of expertise, and follow an agreed upon process.

So, instead of start cursing out loud and making a contribution to put my health in risk at any level, I took three deep breaths and started writing what you’re now reading.

Conventions

I’ve been working with code for 20 years, pretty much the same time version Control Systems have been around, but I started years before they became popular.

Before that, we used to gzip our entire project folder a few times every day, timestamp, and send them to our buddy’s hard drive (via a network cable) as a backup. And hope we never needed to use those!

It’s 2020, Git is here, and each team needs to develop their own conventions and agree on their own standards and best practices. However, when it comes to commit messages, I find these two rules to be fundamental:

Rule #1 Make sure it’s useful

"oopsie!"

Not useful.

"Typo"

Maybe.

"Typo in SignIn.js (build blocker)"

Useful!

When deciding if a comment is useful, think in the context of other commits.

If your Typo message is right above another Typo for example, it will be useful only if at least one of them includes what differentiates the two. Always specify. Don’t be that guy.

Rule #2 Explain what you’re doing, and if necessary, why

Ideally, a good commit message has a very compact first line (50 characters max) summarizing the change, followed by a blank line, and a more detailed description, when needed.

The title (first line) should indicate what was done.
The description, if present, should give more detail about what’s in the title, and explain why.

A good example from Telegram’s git repository:

## Edit korean SentSmsCode string:unnecessary br tag
Although the strings of other languages in SentSmsCode don’t
include ‘<!CDATA..’, the Korean string does that.
Unfortunately, that string is not escaped by replaceTags().
So, the CDATA tag must be deleted.

Once you start doing it, it’ll soon become habit.

Keep reading good stuff:

https://git-scm.com/docs/git-commit#_discussion

https://blog.usejournal.com/make-your-git-history-great-again-da6a8ae799e0

https://chris.beams.io/posts/git-commit