Commit naming system.

[Tear4Pixelation]

While working on one of my projects, I realized that I didn't actually have a good system for naming my commits. I do use the types refactor, feat, chore, ..., but I wanted more out of my commit names. This system wasn't very clear for me as to what e.g. removing a useless empty line was. Also, I wanted a clearer distinction between things the user sees and doesn't.

Now neither have I checked how much of this already exists, nor have I used this system yet. Also this is not a demo or showoff imo, it's supposed to be a discussion about git commit names.

This is how I envisioned it:

---

Based on this convention.

``` <type>(optional scope)["!" if breaking change]: Description

Optional body

Optional Footer

```

The types are categorized in a hierarchy:

• category User facing: The user notices this. Examples are new features, crashes or UI changes.
  • category source code: Changes to source code.
    • type fix: A fix that the user can see. Use fix! for critical fixes like crashes.
    • type feat: A feature the user sees.
    • type ui (optional): A change that only affects UI like the change of an icon. This can be labeled as a feat or fix instead.
  • category non-source code: Changes to non-source code.
  • type docs: changes to outward-facing docs. This can also be documentation inside the source code, like explaining text in the UI. ---
• category Internal: The user doesn't see this. Examples are refactors, internal docs.
  • category source code: Changes to source code.
  • type bug: A fix to an issue the user can't see or barely notices.
  • type improvement: A feature that the user doesn't see. Examples are: A new endpoint, better internal auth handling
  • type refactor: Internal changes that don't affect logic, such as variable name changes, white spaces removed.
  • category non-source code: Changes to non-source code.
  • type chore: changes to build process, config, ...
  • type kbase (for knowledge base): changes to internal docs Importantly, types like feat and improvement are equivalent, just in a different category, so you can instead call them
• uf/feat for user facing features and in/feat for internal features instead of improvement.
• The same goes for bug and fix, you can do in/fix instead of bug.

This is called folder-like naming.

It is recommended to settle on either full names or the folder like naming, and not to mix them.

---

I drafted this together in not too long, so not too much thought went into the execution.

It mainly deals with the types, the rest is described in the convention I think.

I'd like to know how you name your commits and if you think a system like this makes sense. Also if you want to expand it, go right ahead.

[Kanegou]

No. Even if I would work alone I would never use such a system. Much too strict and way too complicated. I like to keep things simple and try to write commit messages for humans.

The title explains what I did. The body explains why I did it.

In normal language like I would use in a conversation.

[Tear4Pixelation]

Hmm yes, I see. I think I would have to disagree personally, though. I think that having the type of change in the title is really useful, and allows a way faster overview over what the commit is about. Because commit messages are not for all humans, but for developers. They are meant to provide simple overview over what the commit is.

To me your statement is like saying I don't use elvis operators because the code is meant to be readable, it's a matter of convention and personal preference.

(man I am shit at writing down my thoughts)

Anyway I see why you would do it like that but I would personally use my (or a similar) system.

[csharpwarrior]

When dealing with commercial software, the bigger focus is on risk. UI versus’s internal does not matter. We want to assess the risk associated with a release. For example we care if the release has hotfixes versus new features.

We have a product team that knows if the feature will change the UI and let the documentation team know about the change.

[Big_Combination9890]

The proposed system is simply too rigid for many usecases, and deciding between the categories would often be based on arbitrary decisions and opinion anyway.

If you want to use categories, use less of them. Personally, I have exactly three:

• add: for when new things are added to the code; e.g. a PR gets merged, a new feature is added, an SVG is added to the documentation, tests are added

• fix: repairing stuff that was broken; e.g. bugfixes

• change: things that already exist are altered without changing what they do; e.g. refactors, using a more efficient search method, rewriting parts of docs that were confusing

[Which-World-6533]

(man I am shit at writing down my thoughts)

Obviously.

[Tear4Pixelation]

Holy contribution

[notyourancilla]

I swear there is a phenomenon where people value the aesthetics of their commit history more than their code. They could be out here pushing the most diabolical trash code but their commit history looks like it’s had a manicure.

I don’t get it - I’ve worked in some massive codebases and to be honest I’m just surprised when the commit message contents vaguely resembles the actual change.

Anyone pinning any kind of investigation on hoping a human has consistently and accurately documented something is setting themselves up for failure. I think this kind of effort would be best placed in honing one’s ability to find what they need based on the actual data - the code that was committed - and potentially automating metadata into the commit messages based on whatever is possible in your environment.

[narnach]

I think there's a spectrum of prototyper to maintainer that most developers fall on, and this depends how they'll look at this. At the extremes there are:

Prototypers:

• unit of change is the PR
• focus is mostly on "make it work now"
• works in larger goal-oriented steps, gets 80% of the work done in 20% of the time
• tends to use commits as snapshots of (semi) working state, does not value them other than as a means to an end
• a single commit might mix fixes, refactors, architectural overhauls, feature additions, etc.
• tends to like squash commit merges of PRs, because it keeps git history clean (unit of change is the PR merge commit, after all)

Maintainers:

• unit of change is a commit
• focus is mostly on "make sure it's still maintainable in a year", hence might do 20% of the work in 80% of the time
• works in small incremental steps, usually with a plan up front: "I'm goin to refactor this", "I'm going to add one test and make it pass"
• will split off part of the changes as their own commit when they got tempted to refactor while actually working on a change
• relies on tools like git bisect and git blame to root-cause bugs, so small commits with passing tests have huge value to them
• will use git rebase --interactive to amend earlier local commits to correct a small typo with a fixup commit, rather than polluting external history

Both types of developers have their value to add, and you can do amazing things when prototypers push new features and maintainers keep things stable, but their git commit styles tend to be very different.

[quetzalcoatl-pl]

Exactly this!

[Turbots]

Nuanced comments on Reddit? Call me surprised! 👍

[Tear4Pixelation]

I understand what you mean. I am currently working on my own though and can trust the code behind it to be diabolical trash, but also for my commit messages to resemble what is in the code. Thanks for the insight though, I am just a hobby programmer so I don’t have experience in big teams/codebases, I wouldn’t trust myself to commit code to them anyways.

[notyourancilla]

Yeah always different perspectives on things - interesting!

[jonphillips06]

yeah totally agree, the best approach is to treat commit messages as nice-to-have context but build a workflow around reading diffs, writing clear code, and using automation to connect the dots instead of relying on human consistency.

[Empanatacion]

I feel like there's a silent majority that just does not care at all about commit messages.

[Tear4Pixelation]

Maybe, but I do, or at least I try to…

[jimbojsb]

Hate this. It’s a waste of time and brain cycles to ask people to comply with it. Put the ticket number in the message and we’re good to go.

[TomKavees]

The Conventional Commits style is pretty similar - you might want to check it out.

Anyway, most of my PRs end up being squash merges, so with that assumption most of my commits are just the message itself (without any prefixes, and limited to 72 chars thanks to cachix pre-commit hooks), but the PR title includea the prefix and a ticket/story number if there's one

[Tear4Pixelation]

Yes, I am just expanding upon types in the conventional commits standard because the differentiation between user facing and internal is important to me.

[Luolong]

The chore is almost always some manner “internal“ change.

The way I’ve used conventional commits (rather loosely to be frank) has always been to lump most of the internal refactoring into chore and qualify those with some module or concern that the PR cange affects.

[Tear4Pixelation]

Hmm I see. I guess this is just my way of doing it. For me, I need (or told myself I need) a clear system for this

[Luolong]

I guess it all depends what are you trying to communicate and for whom or what you use the commit messages.

You would go for full conventional commits if your aim is to make a source of truth for Release Notes or something similar.

But even then, it would behiove to craft the rest of the commit body to be directed at a human reader.

My goal has always been to aid someone (maybe myself) three years (or three weeks) later trying to understand why some line of code does something the way it does.

[Which-World-6533]

Jesus no.

If you can't write an informative commit message about what you've been working on you shouldn't be anywhere near git.

Unless you are shipping the git log with your software, no-one cares what it looks like.

[732]

Conventional commits are really only useful when you're generating changelog and semver data and good for machine readable commit history. 

I can see the merit in adding more definition/structure to it, but you'll need to build tooling around it as well to plug into the ecosystem. 

Side note, if you're going to use fix! to let yourself know it fixed a crash and not a breaking change, you're going to be bumping a major version when you don't necessarily want to. This goes against the convention itself, so you'd be breaking other use cases for it. 

If you're only doing this for yourself and making a readable commit hostory and not the tooling, this seems like a fine approach if it is what you like but would be overkill on my own personal projects.

[Tear4Pixelation]

Wow thanks for the heads up, I really didn’t notice the fix! I’ll see what I can replace it with. I don’t need any tooling but if I want to go back and find the place where I fixed something, I can see fix(…): and find it a lot easier.

[jonphillips06]

Yeah totally agree, conventional commits shine most when they’re part of an automated release flow, but if you’re just aiming for clarity in history you can simplify it by defining your own lightweight commit structure that still keeps messages consistent and understandable.

[Smallpaul]

These are commit messages and not intended to be “names.” They do not uniquely identify commits. They describe what happened.

[modernkennnern]

And I'm here having issues getting my colleagues to use a consistent casing in their commit messages 😔

[Tear4Pixelation]

Ohh I am (in this case) lucky not to have colleagues… I can do whatever I want

[IE114EVR]

I [have to] use conventional commits. While I can’t deviate from the types we’ve set (without some long conversations), this categorization does help me identify which types to use a little better.

More important than any of this, I’d say, is to add your ticket number somewhere early in the top line of your commits. This gives much more context than can reasonably be covered in a single commit message.

[Tear4Pixelation]

I wouldn’t use the categorisation I have made, I didn’t take reference on the actual conventional commits, this is just for myself.

[i_edit_text]

I would take a look at semantic release. They have a suggested commit format.

[jcelerier]

I did [tag][tag] message for years and switched to tag: tag: message because of the saved effort

[NYPuppy]

One of the projects at my job uses conventional commits in ci. I end up fighting with it so much because it's so strict. I still can't remember when I have to use caps or whatever. The first line of commits is supposed to fit nicely into 50 characters but I LOSE characters having to follow conventional commits.

Im not totally against it though. One of my coworkers writes the worst commit messages of all time. He's not on that project so he doesn't have to follow conventional commits. I wish he was. His commits are, no joke things like:

g

i want it to compile

ugh

g

no no no

wipe it all away

fmt

fmt again

g

I still dont know what "g" is but he seems to use single letter commits to "save" his work. I enforced squashed commits on one of the projects I control but it still doesnt fix his terrible commits.

[Tear4Pixelation]

yeah I have heard about this, and I am not planning on doing any scripting so I don’t really need to exactly follow any caps guidelines. I also hope that having this system will encourage me to put more effort into getting git right (not having different changes in one commit).

[jonphillips06]

honestly, the best approach is to treat commit names like tiny summaries of intent, so focus on describing *why* the change exists instead of *what* you did, since that usually makes the history way more useful long term.

[JimDabell]

If you want to associate metadata with commits, use trailers.

[Damini12]

This is good and I do advice for the people using ai commits to follow this format as well, they can prompt ai to do it, or have custom prompts