I just see that as friction. Now a developer who is working on a new feature is reluctant to take opportunities to refactor incase their commit message doesn't match the "standard". Empower the developer and reduce friction to a minimum is my modus operandi.
Plus commit often and plan commits: with the example above the commit messages themselves are becoming a chore. Just make the message meaningful and link it to a JIRA issue or something. That's simple enough for me.
For some reason the fact that "feature" is abbreviated to "feat" while "refactor" which is actually longer than "feature" is left alone irritates me - which, of course, doesn't mean anything other than to demonstrate how silly this kind of argument can be!
Hep, that's very good. I'm trying to do this recently, it is very hard btw unless you organize different topics beforehand, but then it is easy to escape since I often try to do something like "Submodule: ...." because later to merge just a single feature is simpler because commits are "tagged" with the name of the feature or module.
Starting with caps or not makes a huge difference. It can easily break naive grep/awk. Other problems are typos and idiosyncratic spellings. Always spell-check your commit messages, it should be part of your git hooks.
Speaking of Git commit messages, it's worth pointing out this wiki[1], written and reviewed by some long time open source contributors. It's a bit verbose, but rewarding to the patient reader.
On writing Git commit subject lines, I've come to appreciate why the imperative mood is nicer (as opposed to the and indicative mood). Some related reasoning here[2].
Does anyone actually care whether commit messages contain a period or not? If they're lower case, title case, sentence case, it's completely irrelevant
The only thing I care about is whether there's an empty line between the head and body of the (Git) commit message.
I don't care whether the lines are too long, whether they're nicely capitalized, whether they end with a dot. These are all things that tickle my OCD gland but I've learned to ignore them because it is ultimately useless and a waste of my time to get worked up about it. If the summary and description are good enough, I'm a happy man.
(I'm talking about reading others people's commit messages here. I try to make my own commit messages adhere to the scriptures as declared by his Holiness himself: https://gist.github.com/matthewhudson/1475276 (which, I now note, makes no mention of the length of the header line).)
The problem is that if your repo maintainer is encouraging you to use a title as a commit message it implies a different level of information content.
commit -m "Features Aboundin: A new wave"
vs.
commit -m "Added initial project structure for new wave feature."
I'll hesitantly admit that I do, but not enough to blog about it. It's an unconscious indicator for me of inexperience with working with conventional Git, and very (very) often I have to intentionally ignore it for someone's benefit. However, that attitude is rooted in thinking about someone's teamwork abilities; good commit message etiquette, whether regarding periods, conventions on length and formatting, and squashing instead of merging seventeen of your test commits off a feature branch, or just general writing ability and effective communication, are all something I look for in a person.
It's not LITERALLY about the period. It's about how content that contains periods tends to be written a certain way that the author doesn't care for in commit messages.
Considering there are people who have heart attacks based on whether a file ends with a newline or not, commit message formatting is a hugely important topic.
Well his argument is not really the dot at the end, but rather whether the first line of the commit message is a title to the rest of it or whether it is a one-sentence synopsis of the changeset. Examples respectively:
1)
Fix layout.
Replace proprietary grid layout w/ that of Bootstrap,
so that it is easier to manage and use. [...]
2)
Substitute Bootstrap for proprietary grid.
The proprietary grid system was abandoned for Bootstrap,
as it will let us focus on the more peculiar stuff of the
UI.
Commit messages are extremely important when trying to understand the evolution of code. And the style matters a lot, not only the content. The (Linux) style is optimised both for people and tools (e.g. grep, awk).
When reviewing code I held the commit message at a much higher standard that the code itself. Nobody passes through me with a non-perfect commit. Luckily, people quickly learn and they start writing good messages without having me to force them, because they see the value.
A lot of the people commenting on the article seem to be pretty adamant that something like this matters. Personally, I've never been confused by a period (or lack of thereof) at the end of a commit message. And if such a time comes, I'll give serious thought to whether it's worth anyone's time to teach the team to use/not use periods or whether I'm better off investing that time to teach them something more useful.
Well, commit logs could be good complement to developer documentation, if done properly. e.g. "See <some hash range> to see how to add a new protocol to Spyne!" "See <some hash range> to see how a new statement could be added to CPython!."
But, yes, if you care this much about commit format, put structured data in commit logs using yaml or something and be done with it :)
What I care is about the content. And the thing I hate the most are commit messages that explain the what, but not the why! (It's the equivalent to comments in the code that explain something obvious.) To me, this kind of commit messages express the same as if there was no commit message.
But if the commit message says what happened, then you don't need to read diffs to find out what happened. Reading an English sentence is easier than reading code diffs, and also you can read a bunch of sentences in list form (eg, git log).
I'm not saying you don't need to include the 'why', I'm saying there is value just in the 'what'.
As for code comments that just 'explain something obvious'... I have no problem with comments that simply summarise, in English, what the next few lines do. It means I can skim through a file just reading the comments, until I find the part I want to debug/modify/understand in more detail. Also, if you can sum up some code with a sentence then there's a good chance it makes sense, so it's a good quality check.
It's funny how the ones who contribute the least to the functionality have the most outspoken opinions on commit messages. Perhaps it's easier to be puritan when you only handle trivial code changes.
I prefer productive people with messy commit messages over pedantic people with meticolous commit messages any day.
The picky ones usually refuse to touch anything surrounding their particular feature and end up increasing code complexity with every commit, whereas the productive people massage the code into the best possible state as they go along.
> It's funny how the ones who contribute the least to the functionality have the most outspoken opinions on commit messages. Perhaps it's easier to be puritan when you only handle trivial code changes.
According to GitHub, this guy is the author of Redis and he has made 3659 commits to the repository. Call that trivial code changes.
I don't understand how you could possibly tolerate messy commit messages. It's as if you've never had to do a code investigation/audit ever, heaven forbid you do.
Regardless of my opinion about this subject, i always find it good to see when people try to think out of the box.
Nowadays most people just follow what is the current hype:
yeah, let's do semver! And it HAS TO BE react, agile and also it must be in Git, because... yeah, because what? Did you as a developer really think why you are following a certain practice and if it is beneficial to your project at hand? Most people don't. They just do what John Doe posts on his hipster blog about Web3.0.
If you join a team project, you have to follow the team convention. It is not necessary to put dbo. in front of table names in SQL server. Yes, you can use .PHP instead of .INC for class files. No, C# will compile just fine if you indent with four spaces or eight spaces instead of a tab.
However, when you are working in a team, you follow the convention of the team. Or change the convention so the team is on the same page.
I really like bitbucket and JIRA for this in a business use case.
We use the format "JIRA-XXX commit message/title/synopsis/whatever you wish to call it" where JIRA is our project name in JIRA and XXX is the ticket number. Bitbucket then can turn that into a link to your JIRA project
All of the who/what/why is already in the JIRA ticket as more often than not there are non-coders who have input/insight around the issue. When I am looking at the commit log I see a brief summary and if I need more details I can go to JIRA and get the full history with screenshots, designs, reproducible steps, business cases, etc.
Another side effect of this is, when someone is searching in JIRA and finds a ticket they can easily see all of the commits related to that ticket. This also works with Github
The commit becomes simply the "how" "JIRA-XXX brief desc" was implemented
The issue with this is that, over the course of development, the comments on a given JIRA ticket will start to cover QA and release steps, and they drive down the signal-to-noise ratio.
The first comment under the post is frankly outrageous.
This is precisely the reason why the rest of the world abhors programmers and the software community. Random strangers contributing nothing to the debate but their angry and immature bile. No wonder content creators are disabling comments one after another, why wouldn't you?
In a previous gig, we had a simple rule: there must be a ticket number with a certain format at the beginning of the commit message. A summary follows.
The ticket has pretty much all the info you need, so there's usually no need to write a very detailed commit message.
This essentially mandates tickets for every single commit, which might sound too process heavy for some people, but ticketing was part of our process anyway for other reasons (change management, compliance, etc).
In the rare event that a commit is not originated by a ticket, you can still cheat by writing a fake ticket number.
I was recently advised to use the "commit messages are subjects" style, but I get a pang of... something, every time I have to omit the full stop (I always type it out of habit and then press backspace).
I agree completely with Antirez, messages are not subjects or titles, and we should make them as succinct as possible, not force ourselves to write something that leads into a full-text piece only to omit the latter.
If it can fit in one line, make it fit, otherwise summarize the change as well as you can. Our goal should be to have to read the least amount of text to understand what the change is doing, and the hierarchy is: short commit message > long commit message > diff.
> How many emails or articles you see with just the subject or the title? Very little, I guess
I hate to go OT and "well actually", but, well actually this is more common that you'd think. I first learned about "subject only" emails back in 1998 and most places I've worked at use them to convey succinct email messages where there's no need for extraneous words in the body. It's a real time saver when you have a busy inbox.
I've also worked in places that "EOM" (or some variant of) their message subjects to be explicit that there's nothing in the body [0].
WRT to the remainder of the article, I don't have any strong feelings either way.
I also prefer treating them as sentences and prickle at the level of enthusiasm for no dots. In the end consistency with others is more valuable though. However, the article is entirely unconvincing to me, despite being on his side - the removal of a dot and writing succinctly are not mutually exclusive.
It always felt natural to put this dot at the end of (what antirez nicely called) commit synopsis, so AFAIR I always (or at least since I started using git and when was not forced by particular project's rules to do some other way) put it there and found advices to avoid it quite strange. The only exception (beside forgetting about full stop yet pushing to public repo, it does happen sometimes) I have is when the commit is sole version-bumping/releasing one, because then I usually go with following style
PROJECT_NAME [v]VERSION
There are some half-broken SCM managers that always display whole commit message (sometimes even without respecting paragraphs) and then such synopsis without full stop yet followed by another sentences looks rather awful. YMMV
As some commenters here already wrote, it's not a grave matter, but it's good to have consistent style. It goes without saying, that having relatively short commit summary in one sentence separated with blank line from further details (if they are necessary) is far more important matter than the period or lack thereof, as it immensely eases groking commit log.
Commit messages need to convey what will happen if you merge that commit in. Plain and simple. That's all that is needed of them.
Of course, you need to tag the ticket number (in case you are using Cloud based solutions like Github) but I am more interested in what the changes will do if I merge them in.
How about: if your message doesn't fit into a single sentence, the commit is too big. Split it. If it's a huge architectural change merged from another branch, describe it in a separate document referenced in the message.
It seems obvious that inside any given organisation, it makes sense to have a convention regarding the form of commit messages, so you know how to look for certain things.
However, pretending there is a one-size-fits-all rule is taking it too far.
[+] [-] stared|10 years ago|reply
> <type>(<scope>): <subject>
> [...]
> feat: A new feature
> fix: A bug fix
> docs: Documentation only changes
> style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
> refactor: A code change that neither fixes a bug or adds a feature
> perf: A code change that improves performance
> test: Adding missing tests
> chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
There is a big difference in knowing if someone added a feature, fixed something, or did some refactoring.
[+] [-] braythwayt|10 years ago|reply
[+] [-] planetjones|10 years ago|reply
Plus commit often and plan commits: with the example above the commit messages themselves are becoming a chore. Just make the message meaningful and link it to a JIRA issue or something. That's simple enough for me.
[+] [-] arethuza|10 years ago|reply
[+] [-] antirez|10 years ago|reply
[+] [-] Bahamut|10 years ago|reply
[+] [-] 4ad|10 years ago|reply
[+] [-] kashyapc|10 years ago|reply
On writing Git commit subject lines, I've come to appreciate why the imperative mood is nicer (as opposed to the and indicative mood). Some related reasoning here[2].
[1] https://wiki.openstack.org/wiki/GitCommitMessages [2] http://chris.beams.io/posts/git-commit/
[+] [-] BillinghamJ|10 years ago|reply
[+] [-] richmarr|10 years ago|reply
[+] [-] aerique|10 years ago|reply
I don't care whether the lines are too long, whether they're nicely capitalized, whether they end with a dot. These are all things that tickle my OCD gland but I've learned to ignore them because it is ultimately useless and a waste of my time to get worked up about it. If the summary and description are good enough, I'm a happy man.
(I'm talking about reading others people's commit messages here. I try to make my own commit messages adhere to the scriptures as declared by his Holiness himself: https://gist.github.com/matthewhudson/1475276 (which, I now note, makes no mention of the length of the header line).)
[+] [-] weavejester|10 years ago|reply
[+] [-] antirez|10 years ago|reply
[+] [-] sleepychu|10 years ago|reply
[+] [-] jsmthrowaway|10 years ago|reply
I care more about merge commits, to be honest.
[+] [-] ionforce|10 years ago|reply
Did you really not understand that?
[+] [-] zorked|10 years ago|reply
[+] [-] gkya|10 years ago|reply
1)
2)[+] [-] 4ad|10 years ago|reply
Commit messages are extremely important when trying to understand the evolution of code. And the style matters a lot, not only the content. The (Linux) style is optimised both for people and tools (e.g. grep, awk).
When reviewing code I held the commit message at a much higher standard that the code itself. Nobody passes through me with a non-perfect commit. Luckily, people quickly learn and they start writing good messages without having me to force them, because they see the value.
[+] [-] tsiki|10 years ago|reply
[+] [-] plq|10 years ago|reply
But, yes, if you care this much about commit format, put structured data in commit logs using yaml or something and be done with it :)
[+] [-] crdoconnor|10 years ago|reply
[+] [-] knocte|10 years ago|reply
What I care is about the content. And the thing I hate the most are commit messages that explain the what, but not the why! (It's the equivalent to comments in the code that explain something obvious.) To me, this kind of commit messages express the same as if there was no commit message.
[+] [-] callum85|10 years ago|reply
I'm not saying you don't need to include the 'why', I'm saying there is value just in the 'what'.
As for code comments that just 'explain something obvious'... I have no problem with comments that simply summarise, in English, what the next few lines do. It means I can skim through a file just reading the comments, until I find the part I want to debug/modify/understand in more detail. Also, if you can sum up some code with a sentence then there's a good chance it makes sense, so it's a good quality check.
[+] [-] antocv|10 years ago|reply
[deleted]
[+] [-] strictfp|10 years ago|reply
It's funny how the ones who contribute the least to the functionality have the most outspoken opinions on commit messages. Perhaps it's easier to be puritan when you only handle trivial code changes.
I prefer productive people with messy commit messages over pedantic people with meticolous commit messages any day.
The picky ones usually refuse to touch anything surrounding their particular feature and end up increasing code complexity with every commit, whereas the productive people massage the code into the best possible state as they go along.
[+] [-] xiaq|10 years ago|reply
According to GitHub, this guy is the author of Redis and he has made 3659 commits to the repository. Call that trivial code changes.
[+] [-] ionforce|10 years ago|reply
[+] [-] buster|10 years ago|reply
yeah, let's do semver! And it HAS TO BE react, agile and also it must be in Git, because... yeah, because what? Did you as a developer really think why you are following a certain practice and if it is beneficial to your project at hand? Most people don't. They just do what John Doe posts on his hipster blog about Web3.0.
[+] [-] minot|10 years ago|reply
However, when you are working in a team, you follow the convention of the team. Or change the convention so the team is on the same page.
[+] [-] ionforce|10 years ago|reply
[+] [-] chrisan|10 years ago|reply
We use the format "JIRA-XXX commit message/title/synopsis/whatever you wish to call it" where JIRA is our project name in JIRA and XXX is the ticket number. Bitbucket then can turn that into a link to your JIRA project
All of the who/what/why is already in the JIRA ticket as more often than not there are non-coders who have input/insight around the issue. When I am looking at the commit log I see a brief summary and if I need more details I can go to JIRA and get the full history with screenshots, designs, reproducible steps, business cases, etc.
Another side effect of this is, when someone is searching in JIRA and finds a ticket they can easily see all of the commits related to that ticket. This also works with Github
The commit becomes simply the "how" "JIRA-XXX brief desc" was implemented
[+] [-] ascagnel_|10 years ago|reply
[+] [-] emodendroket|10 years ago|reply
I put Github issue numbers into my commits because I use Github. Anything is fine if you're consistent.
[+] [-] VeejayRampay|10 years ago|reply
This is precisely the reason why the rest of the world abhors programmers and the software community. Random strangers contributing nothing to the debate but their angry and immature bile. No wonder content creators are disabling comments one after another, why wouldn't you?
[+] [-] jeremiep|10 years ago|reply
This is what differentiate professionals from amateurs.
[+] [-] nandemo|10 years ago|reply
The ticket has pretty much all the info you need, so there's usually no need to write a very detailed commit message.
This essentially mandates tickets for every single commit, which might sound too process heavy for some people, but ticketing was part of our process anyway for other reasons (change management, compliance, etc).
In the rare event that a commit is not originated by a ticket, you can still cheat by writing a fake ticket number.
[+] [-] StavrosK|10 years ago|reply
I agree completely with Antirez, messages are not subjects or titles, and we should make them as succinct as possible, not force ourselves to write something that leads into a full-text piece only to omit the latter.
If it can fit in one line, make it fit, otherwise summarize the change as well as you can. Our goal should be to have to read the least amount of text to understand what the change is doing, and the hierarchy is: short commit message > long commit message > diff.
[+] [-] WalterGR|10 years ago|reply
You know that you've read to the end of something.
In the absence of one, there's always the chance that text has been cut off
[+] [-] teh_klev|10 years ago|reply
I hate to go OT and "well actually", but, well actually this is more common that you'd think. I first learned about "subject only" emails back in 1998 and most places I've worked at use them to convey succinct email messages where there's no need for extraneous words in the body. It's a real time saver when you have a busy inbox.
I've also worked in places that "EOM" (or some variant of) their message subjects to be explicit that there's nothing in the body [0].
WRT to the remainder of the article, I don't have any strong feelings either way.
[0]: http://lifehacker.com/5028808/how-eom-makes-your-email-more-...
[+] [-] SixSigma|10 years ago|reply
[+] [-] sambe|10 years ago|reply
[+] [-] przemoc|10 years ago|reply
As some commenters here already wrote, it's not a grave matter, but it's good to have consistent style. It goes without saying, that having relatively short commit summary in one sentence separated with blank line from further details (if they are necessary) is far more important matter than the period or lack thereof, as it immensely eases groking commit log.
[+] [-] callmekatootie|10 years ago|reply
[+] [-] jgrahamc|10 years ago|reply
[+] [-] anton_gogolev|10 years ago|reply
I really cannot recall contributors obsessing that much over SVN, CVS or VSS commit messages. Now, you could change these after the fact, but still.
[+] [-] zelos|10 years ago|reply
No, I'm not kidding.
[+] [-] zvrba|10 years ago|reply
[+] [-] tempodox|10 years ago|reply
However, pretending there is a one-size-fits-all rule is taking it too far.
[+] [-] maxehmookau|10 years ago|reply