Who are you writing that commit message for?

I read a lot of commit messages that make me wonder who the committer had in mind when they wrote it. If you don't read commit messages yourself, I think that can make it even more difficult to think about who the audience is, or when someone would be reading those entries. Perhaps you're writing for nobody, or work in a team that doesn't value the metadata that a single sentence written in the moment can deliver.

Next time you write a commit message, try some of these suggestions as your imaginary audience:

  • Yourself, next week, when you finally get back to working on this thing and can't remember where you were up to
  • Yourself, when you get a pull request review and can't remember which commit something is in that needs to be removed
  • Yourself, debugging how this ended up like this, 6 months from now
  • Your colleague, eyeballing your work to see how you are getting on

Personally, I think of it as a note to myself. Like an alibi, if someone asks you what's already been done, or what this commit that removes one specific line from a long config file. Yes, I worked as a git consultant for a while, the delete-a-single-line with the commit message "Fixed" is always the culprit!

Further reading: https://cbea.ms/git-commit/

VSCode setup for technical writers

I'm working almost entirely with docs-as-code setups for prose at work these days and while I do use vim for most of what I do, VSCode is increasingly in the mix. It's just about accessible enough with keyboard shortcuts and the command palette for me, and I thought I'd share the extensions I'm using and find helpful. Continue reading

Ubuntu Command for Mic Mute with Pulsemixer

One of the major problems I run into with video conferencing tools is how many of them are not at all accessible. I'm a keyboard-only user so if I need to hover a pointer in a particular area of the screen and then click an icon to mute ... then I can't do that. And if you mute me when I join because there are a lot of people here, then I can't participate at all. To work around this, I need a one-liner to mute (and unmute) my mic ... so here it is. Continue reading

Combine Multiple Field Tags in Go

I work a lot with JSON APIs in my Go projects, so almost every struct has some field tags on it to translate AccountID into account_id and that sort of thing. Then one day I needed to load data from config using mapstructure and it took a few attempts with the search engine to find the syntax I needed, so it's here for next time I need it (or in case you need it too). Continue reading

Using Environments in Postman

I'm using Postman more lately and showing off the Environments feature really often. I really like this feature for giving easy ways to handle values I use frequently, but it seems to be a bit of a hidden gem, so I thought I'd write about when I find it useful, in case you do too! Continue reading

Accessing Nested Config with Viper

I'm writing a Go application that glues together a bunch of other things, so it has a whole bunch of basically unrelated config, dumped in a yaml file. I was struggling a little with this non-standard use of Viper but actually, it does everything I needed. And, presumaby, more besides. I thought I would put some examples here to show how to handle this. Continue reading

Remove Accidental Content from Git Commit

When I teach git I try to show loads of good practice about how to inspect what's staged before commit, etc etc. Good practice is good of course, but knowing how to undo a mess you created is better - and mistakes will happen. For example, accidentally including a node_modules directory in your otherwise excellent and useful commit. This post will walk you through how to fix the problem without losing any of your work. Continue reading

Counting Duplicate Commit Messages

When chatting about source control good practice the other day, I got a question about repeated git commit messages. In general, I would always advise that the same commit messages appearing multiple times in a project's history is a definite red flag - and if I'm responsible for that repository I will probably make fun of you for doing it. Continue reading