Hacker News Reader

Comment by kccqzy | Hacker News Reader

Long ago I changed the default commit message to include headers “Why?” and “How?” to remind myself that I need to explain why a change is made (what this article focuses on), and how it is made (different implementation approaches considered). I followed this format for a long time. I was in the top 1% for commit message length at the company.

Tangent: I once worried about things breaking when commit messages got too long. I tried really long commit messages and nothing broke: https://github.com/kccqzy/long-commit-messages/commit/ccfda4...

View on HN

I like the Git rule of thumb. If it's too long -- it's probably not a single commit.

Why make this change at all? Why do it this way? What would have been the next best way, and why not that? What important assumptions justify this? What's next for this? etc

To stay concise, I think bullet trees are the best. I've never had to make exceptions to this format.

Top level groups high-level concerns (optional). Below that (required) are short distillations of those concerns answering "why". Below that are descriptions of "what" was/wasn't done. A final optional level digs into deeper implementation detail.

The vast majority of my bullet trees are just those two required levels. Each commit message is rarely more than 10 or 15 lines long, and people really appreciate them. I appreciate them too since I'm the most likely to read them.

Got an example of what you mean?

A full example of all levels would be something like this. Generally, I think I'd have split up this commit to remove the top-level bullets, and more splits means fewer bullet levels.

Also, due to HN comments not being the best with formatting this kind of thing, I kept these lines very short. It's the gist that matters most.

I don't know where I picked up this style, but it was before I ever got hired anywhere. It was common across several places I worked at later on in the 2010s. I strongly prefer this to rambling prose. The first line is the Jira ticket description, by the way.

  MYPRJ-73: Auth bug redirect loop

  - Frontend router fixes
    - Check cookies before redirect
    - Default redirect to login page
      - New case added for "expired"
  - Backend
    - Update repurposed Apache config
      - Remove old DBM
    - Update cookie response header
      - Don't use "SameSite=Strict"
        - Removed 3rd-party lib
        - We own this code for now

Reply on news.ycombinator.com