Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Write commit messages for humans #735

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Write commit messages for humans #735

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions git/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@stevepolitodesign stevepolitodesign Mar 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@nickcharlton nickcharlton Mar 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

😃

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some examples:

  • Group Rails guidance into sections #725
    • I used a style type prefix at first because I wasn't adding new content, but working on style and layout
    • I used refactor to show I committed some rework
    • I also used fix to show I was addressing a linting issue. Which on a code project could be style, 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
  • 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 style commits, one for each rule, all scoped to markdown
    • due to the technical nature, the commit descriptions cover more of WHAT was done

more references:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

other Git patterns).

[rebase workflow]: https://github.com/thoughtbot/guides/blob/main/git/README.md#merge
[good commit message]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
Expand Down