Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Semantic Commit Messages

Semantic Commit Messages

See how a minor change to your commit message style can make you a better programmer.

Format: <type>(<scope>): <subject>

<scope> is optional

Example

feat: add hat wobble
^--^  ^------------^
|     |
|     +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.

More Examples:

  • feat: (new feature for the user, not a new feature for build script)
  • fix: (bug fix for the user, not a fix to a build script)
  • docs: (changes to the documentation)
  • style: (formatting, missing semi colons, etc; no production code change)
  • refactor: (refactoring production code, eg. renaming a variable)
  • test: (adding missing tests, refactoring tests; no production code change)
  • chore: (updating grunt tasks etc; no production code change)

References:

@tykeal
Copy link

tykeal commented Aug 5, 2021

@JohnnyWalkerDesign:

@sharpvik Hey, nice tool. I've never seen a repo or a guide say to use capitalisation, though. Your default setting should probably follow the established guidelines?

https://www.conventionalcommits.org/en/v1.0.0/

While all of the CC docs show lower case, I and my team enforce the seven rules of great commit messages put forth by Chris Beams. Of which, rule number three is 'Capitalize the subject line'. It's even in the Git book.

As an aside on that, short logs are significantly easier to read if all subject lines are capitlized

@marijoo
Copy link

marijoo commented Aug 20, 2021

Using semantic commit messages for quite some time now. Still not sure what to use for simple content updates such as changing a headline or a hard coded email address. I mostly go with chore – any recommendations?

@tykeal
Copy link

tykeal commented Aug 20, 2021

It's either that or docs. Chore definitely sounds like the more appropriate one though.

@marijoo
Copy link

marijoo commented Aug 21, 2021

@tykeal Yes, think so, too. But here is what bugs me from a CI perspective:

When using semantic-release chore or docs would not trigger a new release which seems absolutely right. But to me a new version release is the best deployment trigger and a content change should be reflected immediately even though it‘s not „a feature“ imho.

@aleksandervalle
Copy link

aleksandervalle commented Aug 23, 2021

I've always had trouble labeling these types of changes (context is Azure):

  • Changing configuration provider in a backend service. E.g, change from using environment variables or settings file, to Azure App Configuration service.
  • Change authentication method. Instead of connection string, use managed identity
  • Upgrade dependency, and update code to accommodate breaking changes.

Not 'chore' – these examples definitely changes production code.
Not 'refactor' imo – these examples don't simply change structure of code.

I feel 'refactor' is closest, but it doesn't quite fit. What do you think?

@sharpvik
Copy link

sharpvik commented Aug 23, 2021

I'd say that chore fits better. These are not changes that a client would really see. Now, granted, refactoring also doesn't really change the visible side of things, but I always imagined it to be related to the code we write instead of infrastructural changes like changing a library.

IMHO, the best option for stuff like this is probably a separate label that didn't mean much sense in the context of Angular, but makes a lot of sense in the server side development: 'infra' for infrastructure.

I think I will add 'infra' to my tool sema.

@JohnnyWalkerDesign
Copy link

JohnnyWalkerDesign commented Aug 26, 2021

Using semantic commit messages for quite some time now. Still not sure what to use for simple content updates such as changing a headline or a hard coded email address. I mostly go with chore – any recommendations?

Semantic commit messages take their lead from the Angular project's contribution guidelines:

Type

Must be one of the following:

  • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
  • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests

So simply it's refactor. That's it.

@AlFarizzi
Copy link

AlFarizzi commented Sep 2, 2021

nice info

@marijoo
Copy link

marijoo commented Sep 2, 2021

So simply it's refactor. That's it.

@JohnnyWalkerDesign I’d agree with @aleksandervalle that it is not simply a change of code structure. And using refactor would not trigger a new release. Let’s say I have a static page with terms of use and those are changed which imho would legitimate a new release.

Plus a refactor for me is restructuring code and has nothing to do with content.

@refaldodev
Copy link

refaldodev commented Sep 6, 2021

Thanks bro 👍

@sametcelikbicak
Copy link

sametcelikbicak commented Sep 16, 2021

Thanks, very helpful content 👍

@JohnnyWalkerDesign
Copy link

JohnnyWalkerDesign commented Sep 16, 2021

@JohnnyWalkerDesign I’d agree with @aleksandervalle that it is not simply a change of code structure. And using refactor would not trigger a new release. Let’s say I have a static page with terms of use and those are changed which imho would legitimate a new release.

Plus a refactor for me is restructuring code and has nothing to do with content.

I agree with you, but this is where these terms originate. Given that Angular doesn't have "content" (it's a framework after all), it sounds like Semantic Git Comments should adopt a new term. Maybe content: for changes unrelated to fixing bugs, new features or code structure.

@guneyozsan
Copy link

guneyozsan commented Sep 16, 2021

@marijoo I think changing a headline should be handled similarly to a change in UI.

For example, if one of the UI buttons were misaligned, that would be a fix. If you introduce a new button, that would be a feature. It should be the same for UI text as well. Fixing a typo should better be a fix. And introducing new text, or updating an existing text should be a feature.

chore, docs, or refactor are for the development side of things. But a change in the headline is a user-facing change.

@JohnnyWalkerDesign
Copy link

JohnnyWalkerDesign commented Sep 16, 2021

There's already a style tag that relates to code style. Hmm. The more I think about this, the more I think the current options are half-baked and not ready for primetime.

@Azaferany
Copy link

Azaferany commented Oct 6, 2021

that's handy!, thank you!👌

@201flaviosilva
Copy link

201flaviosilva commented Nov 25, 2021

Thanks! 😁 I always forget that 😅

@YodaEmbedding
Copy link

YodaEmbedding commented Dec 5, 2021

Code-only "features"

What about "features" that add functionality to the code base, but aren't anything that the user of the application cares about?

Example addition:

funcs = []

def register(f):
    funcs.append(f)
    return f

"""
Now the developer can register functions... yay!

@register
def say_twice(s):
    return f"{s} {s}"
"""

This change helps only the developer in the future. The user is not affected at all. What is a good commit message?

feat: add function registry decorator

@coolaj86
Copy link

coolaj86 commented Dec 8, 2021

This omits the use of !, such as feat!(auth): require two-factor.

The ! after a type indicates that it may be a breaking change or is otherwise suspect for issues that arise.

Would you also add ! to this document?

@Ali-Ta24
Copy link

Ali-Ta24 commented Dec 23, 2021

thanks :)

@AJohnsoon
Copy link

AJohnsoon commented Dec 27, 2021

I still have doubts when to use the chore, can someone explain to me?

@dheysonalves
Copy link

dheysonalves commented Jan 6, 2022

@AJohnsoon I would think that is the scenario which all others scenarios does not fit. I would think as a dependency upgrade. But to create a hypothetical use case.

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Example taken from: https://www.conventionalcommits.org/en/v1.0.0/

@AJohnsoon
Copy link

AJohnsoon commented Jan 17, 2022

@dheysonalves oh, thanks for help !

@sakilk130
Copy link

sakilk130 commented Jan 24, 2022

thanks

@born-kes
Copy link

born-kes commented Jan 31, 2022

thanks @joshbuchea
and thank you also @JohnnyWalkerDesign

@alwayswelcom
Copy link

alwayswelcom commented Mar 21, 2022

feat: video player

@ralphwbms
Copy link

ralphwbms commented Mar 30, 2022

Why everyone use 'add' and not 'adds' to the commit message? Looks to me that the hidden subject is 'It'. E.g.: 'It adds something'.

Sorry if it's a silly question. I'm not a native English speaker.

@JohnnyWalkerDesign
Copy link

JohnnyWalkerDesign commented Mar 30, 2022

@ralphwbms It's what the Git documentation specifies as the standard: Present tense.

@tykeal
Copy link

tykeal commented Mar 30, 2022

Great commit messages will adhere to several "rules". Rule 5 of https://cbea.ms/git-commit/#seven-rules states:

Use the imperative mood in the subject line

And this is backed up by a lot of material, just look through the various links above the listed rules. I do recommend that you read the whole of the Chris Beams article as well as David Thompson's article on helping to improve your commit messages. These, along with the semantic / conventional commit message really improve commits!

@guneyozsan
Copy link

guneyozsan commented Mar 30, 2022

@ralphwbms Similar to a function name, the commit message describes not the action itself but how the data is modified (in this case the data is your code). Think of a commit as a building block so that you can read through the commit history like a recipe (or a pseudo-code).

@ralphwbms
Copy link

ralphwbms commented Mar 30, 2022

@JohnnyWalkerDesign , @tykeal , @guneyozsan

Thanks everyone for the tips and quick answers 😄 I will definitely check them out.

I've been using the correct patterns for commit messages for some time now, but I've never understood why the verb doesn't have the 's' at the end, as we are giving an order (imperative form) to a thing (Git), which implicitily is a 'It'. But I just realized that when we give an order to a thing in English, we also use "you", and not "it". So, the subject doesn't change as I thought, It keeps being 'You'.

Sorry for the confusion guys. But talking about it made me finally understand WHY 😄

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment