Write commit messages for humans #735
Conversation
You should tell a story for your fellow programmers, not fit within arbitary rules followed in other places. However, if the repository is already following such a rule, you should do so for consistency.
|
I wish for a better argument for why here, but I ran out of ideas. Aside from reading fairly "robotic", it's usually meaningless (what even is a chore? isn't all programming at some level, a chore?) and typically not even used for anything. Making the words harder to understand. |
| @@ -7,6 +7,8 @@ A guide for programming within version control. | |||
| - Avoid merge commits by using a [rebase workflow]. | |||
| - Squash multiple trivial commits into a single commit. | |||
| - Write a [good commit message]. | |||
| - Write commit messages for humans, not machines (i.e.: avoid "chore:" and | |||
There was a problem hiding this comment.
I actually don't mind those prefixes, since it gives me context as a scan through the commit history.
What I find most valuable (and what I think you are proposing) is that each commit explains the why, and not the what. This might relate to #734.
There was a problem hiding this comment.
Yeah, it's all about being purposeful with how you go about your changes, which is why I ended up doing this right after #734.
Does prefixing your commits provide value for other humans? If we're doing that consistently throughout a repository, go ahead. Otherwise consider if it's better to express yourself in a more human way.
There was a problem hiding this comment.
Does prefixing your commits provide value for other humans?
I think it can, but there's a nuance to it. For example, the last two PR's I closed were prefixed with "Rails", which I think was beneficial.
On client work, I also prefix commits with "Feature Name:" to give added context.
That being said, those are not Git patterns. I think I'm just getting hung up on the prefix part.
There was a problem hiding this comment.
😃
Along those lines, there's a common pattern that I see followed often in Go where you highlight the area of code changed in your commits. Now, I think this is likely something that's come from using monorepos (a different topic, but something else I think is a horrible idea) where that's much more meaningful. But, I've seen people follow the same pattern where you mention the file, or sub-directory or equivalent. You don't need to do that! It's in the diff!
I went for a walk earlier and I thought that another side of this would be: if you're going to follow a specific pattern you should be linting for that.
There was a problem hiding this comment.
I often follow the conventional commit format (https://www.conventionalcommits.org/en/v1.0.0/#summary) and I usually find prefixing commits to be highly valuable.
prefixing and following a standard format facilitates a level of cognitive funneling. When a commit is prefixed with a type, a human searching through the history can make a quicker judgement call if the commit is relevant to what they're looking for. If they're looking for new features, they look for the feat: prefixes. If it's a bug fix then fix:. The format <type>[optional scope]: <description> lays out information so that as you read it, you are presented the broadest level of details first and the most narrow and specific last. Including scopes helps with this even more. If what I'm searching for doesn't fit the type or scope, then I don't even have to read the description.
Knowing I need to tag and scope my commit message can also encourage me to keep my commits smaller and more atomic. I shouldn't fix a bug, develop a feature, modify CI config, update docs, add tests, fix style and refactor all in one commit because each of those have their own type tag and I can make granular commits for each of them. Also, if I get carried away making too many changes without committing, the format then encourages me to break up my work into smaller commits to write a commit message that conforms to the format.
There was a problem hiding this comment.
Some examples:
- Group Rails guidance into sections #725
- I used a
styletype prefix at first because I wasn't adding new content, but working on style and layout - I used
refactorto show I committed some rework - I also used
fixto show I was addressing a linting issue. Which on a code project could bestyle, but the exact mapping of types isn't consequential; it's important that in any one context everyone uses them the same way (a ubiquitous language if you will). - My commit descriptions were still more oriented towards WHAT rather than WHY, but the context is clear (I'm still working on this myself
- I used a
- Add Markdown Linting #726
- I introduced Markdownlint, so that was a new feature (
feat:) - configuring the linting rules related to conventions and style guide, so I used
style: - I configured the linting to run on github actions -- related to the
build: - lots of
stylecommits, one for each rule, all scoped tomarkdown - due to the technical nature, the commit descriptions cover more of WHAT was done
- I introduced Markdownlint, so that was a new feature (
more references:
There was a problem hiding this comment.
addendum — I've focused more on the human aspects above due to the conversation, but following a standard commit structure is also useful for automation and tooling (for example: automating the generation of CHANGELOGs). Though this can again be reconnected to the human aspect, if you have a standard set of tokens/slugs/prefixes in your commits, then a human can more easily use command line tools to filter the git history
You should tell a story for your fellow programmers, not fit within arbitary rules followed in other places.
However, if the repository is already following such a rule, you should do so for consistency.