Defensive Commits

Git commit styles are one of those things that get argued over endlessly, like code comments, or the proper size and scope of functions. But I have a simple rule with mine.

Write like you're being git blamed, and you have to defend your choices.

The top line says, as briefly as possible, what the commit accomplishes. Include ticket or issue numbers. This helps people locate a particular commit, locate the work context for the commit, or understand at a glance what it was attempting while they scan the log.

The next lines are where I defend myself against my accuser (which is often Future Michael) and explain why I did this unnecessary-looking thing, or why I implemented this solution and not that one. Whether the reasoning was right or wrong, it helps my future readers understand what they need to keep in mind when changing it, or whether they should leave it alone.

commit 52259873aefbc4215e3378295086627e85f1c66b
Author: Michael Endsley <[email protected]>
Date:   Mon Apr 15 20:20:37 2024 -0500

    INFR-2059 Make QA deploy a dynamic child pipeline

    In order to leverage resource groups with QA deploys, and be able to
    specify exactly which QA environment is being targeted with the
    `environment` keyword, just do a poor man's templating with sed to
    generate the child pipeline to be executed. It's possible to define the
    resource group for an entire pipeline instead of for each job in the
    pipeline, but that would require 2 child pipelines (1 to use the dynamic
    resource group name to spawn the 2nd). I find this way simpler.

The context of this commit here isn't important to get the point, but for the curious this was written about some Gitlab CI pipelines leveraging resource groups for deployment jobs where the target AWS account -- an ephemeral QA environment -- wasn't known before deploy time.

Now when Future Michael (or my successor) is perplexed about why Past Michael added a resource group to each job in a pipeline instead of wrapping the whole pipeline in a group, he knows why.

Some folks reserve this kind of commentary solely for PRs. It's fine there, and as long as nothing dramatic happens to the git host, project, or the PR record itself you'll retain that history, but I believe in putting it in the commit log first. The git host is more fragile than the commit log itself, and it's extra effort for anyone reading my code where they found this perplexing change to go find its PR and (hopefully) get my thought process about it.

Next time I git blamed for something in the codebase, I'll have my defense prepared.