renfoc.us

Metaphysics, tunes, and code

2-13-2025

A Good Commit, with Empathy

It is easy to miss good solutions. The best type of solution is the one that feels natural, hence invisible. Good commits tend to fall into that spectrum.

For those who aren't fluent in programming lingo, commits are a way to save the state of our work, like you'd save your progress on a videogame.

Git commits allow us to go back to a specific point in our progress to see or revert changes made to a project. Since projects are often worked on between multiple people, the safe states come from all the members working on it.

A commit is mainly made up of:

All of these items are accessible to the people working on the project.

What is a Commit Message?

Focus not on the what but the why.

Developers have access to both a unique identifier and the file changes. This leaves the message with the high order responsibility to contain everything else. A commit message is the description of the state outside of the file changes.

The message should be able to fill in the following sentence: "IF APPLIED, THIS COMMIT WILL _________" without describing the code changes.

Empathy Wanted

Generally, we code in packs. Just like another relationship, communication is essential. These git messages are a way to tell a story, and we should take advantage of that. When we successfully understand our code as affecting others, we can begin tackling major issues impeding progress. Progress halts when

The following is an example of a commit message that lacks empathy:

commit ce820a9da
Author: ren-rocks 
Date:   Mon Feb 4 11:23:07 2021 -0500

    quick fix


What is a Good Commit Message?

First of, a good commit message follows the generally accepted structure. There are tons of posts about a good commit structure.

commit b3ed56c94a7
Author: ren-rocks 
Date:   Mon Mar 1 23:02:47 2021 -0500

    fix bad parsing due to v3.1 API changes

    changes to the NYT API response broke 
    the regex string.

    this change removes patch ce820a9dd. The
    new regex handles both endpoints.

    endpoints updated: topStories and 
    latest.

    an alert has been added to check for
    future API changes so we do not go 
    through this again.

    find the new alert in card 38t90

Aside from the general commit rules, a good commit message

and has at least a few of the following:

Ideally, we can make each other's lives easier. I hope this post helps to do that.