Commit messages are not titles
antirez.com
antirez.com
> <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.
Yes, it called the Unix philosophy, good programs do it.
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.
Honestly those commits should probably be split anyway. A commit should represent the smallest 'change' which is singificant.
Which again may result in that refactoring never getting done. Many times I've found myself saying to myself "I must refactor this class.. But I'll just finish implementing this feature first so that I can get a clean commit with only the refactoring afterwards". Suddenly it's 5 o'clock and tomorrow I've forgotten about the refactoring need.
You already know you want to refactor it so its not about forgetting to do it, and once the feature is done you'll probably have a better idea of how to refactor everything better and faster. It should actually save time in code productivity vs the extra minutes to do another commit.
I just write new features, refactor if needed, fix unrelated bugs, etc. When I feel like it's commit-time, I cherry-pick changed chunks or lines to commit into single coherent commits. If I've introduced a new feature that required refactoring, I'll first pick all the chunks that belong to the refactoring and commit; then I'll commit the new feature and afterwards commit any bugfixes and other side endeavors that may have come up during the development of the new feature.
This is one of the reasons I don't like working with Subversion anymore. Committing, say, two changed lines in a file with many changes is nearly impossible. In 'git gui' it's a simple as selecting the lines, right-click, "Stage lines for commit" and pressing the commit button, and I'm back to working on whatever it was I was really working on.
So I'm stuck with undoing my feature code or leaving smells of my feature in the refactored code.
Maybe I'm doing something wrong though.
Having maintained a few projects on Github, I routinely reject commits that both introduce new features and fix/refactor things. Refactoring is good, but jumping on a project and changing everything at once is a strong indicator of a lack of focus. The "fix some of everything" commits usually lack tests and documentation updates which wouldn't have been overlooked if the contributor took a step away and looked at the big picture.
- Refactor to prepare for Feature X - Implement Feature X
Note that these can be written in parallel, but just submitted as two separate commits (guess which side of the history editing debate I come down on :) )
(In any case, I don't use Angular-style commits for all projects. But learning about them was a small (but important) step in reducing complexity, vide http://www.johndcook.com/blog/2015/06/18/most-important-skil...)
I'm curious:
In any tool for any revision control system ever: in a list of commits, are the commit messages augmented with something useful beyond the basics? ("Basics" being e.g. the first 'n' characters of the human-provided commit message, a revision identifier, a timestamp, and a username.)
Jira and other ticketing systems can often read repos and look for ticket ids. In my commits at work I just mention PRJCTNAME-142 and that'll link to a ticket and aggregate in jira all the commits/pull requeusts/branches... tagged with that
There is a big deal of subjectivity (e.g. what is a bug, and what is a feature) but (as with any comments in the code) it is nice to see at least what was intended (e.g. someone wanted to position a misaligned button, or added it, or improved its visuals or optimized its click from O(n!) to O(1), ...).
Well, for starters I wouldn't have a commit message stating that I just added a bug, though I might have one stating that I added a feature. :P
In fact, it could be a very good thing, especially if the alternative is, eg, dropdowns for type and scope, and a separate popup for editing or adding new ones, and so on.
Having the data model loosely encoded as text, and understood only by convention among humans, who can then improvise changes to that model in exceptional cases, relying on other humans to make sense of those changes even though they are "outside" the agreed-upon model, is sometimes exactly what you want.
Also, as UI for input, text is often the fastest and most efficient -- again, just what you want. Of course, you could always do string validation on the text input to enforce your model, so this can be considered an orthogonal point.
And these considerations don't even touch upon the increased complexity and maintenance costs that your tool itself (in this case, git) will incur if it takes on the burden of maintaining the data model explicitly.
The UX exists for the reader, the data model for the programmer. Sometimes, text is the best UX. For example, I love Markdown, a classic example of a data model serialized as text. I do not want a “rich editor” that speaks the data model directly.
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/
Add comment strongly agreeing with parent
The links in the parent comment are to documents which are
prescriptive, based on hard-earned experience, and provide
well-reasoned justifications for how and why to format commit
messages, along with examples of projects which do so.
I wish the parent comment were at the top of the page, but I can
provide only a single upvote. This comment is to provide more
exposure than an upvote alone, and so that I can find it my HN
history.- https://en.wikipedia.org/wiki/Bookmark_%28World_Wide_Web%29
- Direct link to parent comment: https://news.ycombinator.com/item?id=9764039
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).)
I care more about merge commits, to be honest.
FTFY.
"A source file that is not empty shall end in a new-line character [...]"
So if your C implementation doesn't complain about source files that don't end with a newline, you're unknowingly relying on a language extension.
(make sure to hit F5 a few times)
If you can't get quickly to an agreement about such a thing, or if the members of the team that didn't get their way actively rebel (or worse sabotage), you are working with a team of divas.
(note: of course developers whinge, as long as you stick with the team decisions once their are made, whinge all you want)
Or you're working on such a trivial problem that it should have been given to an individual, not a team.
A well working team will probably do as you say - volunteer an individual to write the rule in an email and follow it from there on.
If you going to introduce changes in a team, like for example introducing Agile (the proper way) or you are starting a new project, you want to quickly gauge the team dynamic, and that's a good exercise.
It kinda reminds me of that buzzfeed article "53 Signs Your Boyfriend Is Really Three Children In A Trenchcoat".
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.
Maybe it doesn't have any effect when reviewing _one_ commit message, but when you're reading a list of hundreds, or thousands of them, it does have a huge impact.
This messages are meant to be consumed by humans, as in natural language. So it should respect the rules / conventions of that natural language.
The same way when we write code we should respect the coding style of the code base we are working on, we should respect the style conventions of the natural languages. Because of the same reasons.
People generally accept that when it's about coding conventions. Commit messages are just another convention. The rules are not arbitrary, in fact, if you read the Linux commit style guide, it will try to explain the value of the conventions.
If you still don't get it, or you disagree, too bad. Conventions are much more important that individual opinions. If you prefer spaces, you'd better start using tabs when you want to contribute to the Linux kernel.
(By you I meant, of course, some abstract person who doesn't see the value of certain rules, not kolme who I am responding to).
Of course in the case of projects a developer is working on solo, they're free to do whatever they want ;) When I'm working with others, I still express my own preferences, but I'm willing to go along with whatever the group consensus is because I'd rather be consistent above anything else.
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 :)
Did you really not understand that?
1)
Fix layout.
Replace proprietary grid layout w/ that of Bootstrap,
so that it is easier to manage and use. [...]
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.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.
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.
As for code comments, I think you're basically wrong. If you can summarize some fragment of code under a sentence, extract that piece of code into a method and name that method in the same way you were going to write that comment; otherwise comments get outdated easily. These kind of techniques are well explained in a very good book I read a while ago, it's called "Clean Code".
Personally I think check-in comments should be a concise (but not generic like "bug fix") description of "what" with a smattering of "why" (perhaps a reference to a bug/ticket/feature/request ID). The details of "what" can be seen by looking at the diffs. Where the details of "why" go is split. Why you chose a particular method over others available? Any constants or magic numbers you think might need clarifying when someone else looks? You've done something that looks odd/unnecessary at first glance in order to work around a bug/limitation beyond your immediate control? Those things go in comments in the code. Just about everything else goes in the ticket and possibly makes its way to other documentation, there is not point cluttering the code up too much (unless your implementation documentation is all in-code and you use tools to extract it into other forms, as I've seen done before now, in whic case everything goes in there). "FIXME" and "TODO" markers can go in the code too though generally you want them gone for release (if they survive between releases then they should really be feature requests in your backlog rather than just code markers, so they can be tracked/managed/prioritised as needed.
What really grinds my gears is commits without any comment at all.
That just shouldn't be allowed. Commits without JIRA (or whatever you use) task reference should just be automaticaly rejected.
"otherwise comments get outdated easily" - not mine. If this is a problem, it's a problem that needs fixing, not a reason to comment less.
"extract that piece of code into a method" Sometimes, yes, but you can overdo this and end up with a fragmented codebase that is harder to follow.
This is an old debate, and there are books on either side. My preference is something approaching Knuth's literate programming.
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.
According to GitHub, this guy is the author of Redis and he has made 3659 commits to the repository. Call that trivial code changes.
The commit messages are nice as indicators of intent, but I don't rely on them. The real change is in the code, not what somebody remembered to write in a summary of the change.
"new feature. fix it. fixed. lol. WIP. COMPILES NOW"
None of these tell you how the commits came to be other than that they are already there.
I mean, it's pretty easy. You just like, tolerate it.
I'm sure there are contexts where strict rules are important, but in my experience most of the time fussy commit message rules are put in place it's because someone has reimagined themselves as the gordon ramsey of code and the people rolling their eyes don't want to get entrenched in a political battle where they're against "professionalism", so they just deal with it, or someone with mild OCD is inflicting it on everyone else. (I know I'm being harsh and I'm writing this tongue in cheek, I don't really think that badly of people that are super fussy about these things, but I've rarely seen any actual utility come from strict commit rules).
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.
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.
Depending on default schema, it definitely can have performance considerations on compilation.
Maybe some of those team conventions are actually based on real world things.
From: https://msdn.microsoft.com/en-us/library/dd283095%28v=sql.10...
SELECT * FROM Table1
Will assess the following statement first: SELECT * FROM <defaultschema>.Table1
If it cannot find the object, the server will assess the following statement: SELECT * FROM dbo.Table1.
The assessment process can be improved by using either the fully qualified name or the DEFAULT_SCHEMA option described earlier. By setting a value for DEFAULT_SCHEMA for the user, the server will check the DEFAULT_SCHEMA first, removing an unnecessary ownership checking process. This can improve performance considerably on heavily utilized systems.
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
I put Github issue numbers into my commits because I use Github. Anything is fine if you're consistent.
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?
This is what differentiate professionals from amateurs.
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.
A la the Joel Test, your ticketing system should:
- open a new ticket on receipt of unknown email, sending back the ticket number
- treat email with a proper subject prefix as a comment on an existing ticket, adding any attached files
- easily merge two or more tickets, preserving both histories and redirecting all references to the old tickets to the new one
- maintain metadata and ACLs for metadata
- automatically re-open a ticket when a new comment or reply is received
- require a message to close a ticket
- provide summaries
- be full-text searchable
- track all history immutably
- provide a method to associate many individual reports of the same problem
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.
I get a pang of... something, every time I have to omit the full stop
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
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-...
PROJECT_NAME [v]VERSION
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.
Actually TL;DR both are important.
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.
This "mentality" seems to have leaked out of the machine and into the mindsets of developers. Just like learning a functional language will alter the way you think so will learning a SCM that values history (which DVCSes typically do).
No, I'm not kidding.
However, pretending there is a one-size-fits-all rule is taking it too far.
Reading between the lines, it seems that the 50 character limit is to accommodate commands like "git log --pretty=oneline" and "git rebase --interactive" on an 80 column terminal. He also recommends 72 columns for any subsequent text because git makes a left margin of 4 characters and it looks balanced if you also have a right margin of 4 characters (80 - 8 = 72).
As someone who actually uses an 80 column terminal, I appreciate this practice. Probably younger people with good eyes won't be able to understand the reasoning behind it ;-)
Serious question, have you tried reading glasses? You don't have to just deal with bad eyes as you age, you can wear reading glasses. This what I do now.
chore: add Oyster build script
docs: explain hat wobble
feat: add beta sequence
fix: remove broken confirmation message
refactor: share logic between 4d3d3d3 and flarhgunnstow
style: convert tabs to spaces
test: ensure Tayne retains clothing
Commit messages ought to consist of a title, followed by an empty line and a short(-ish) summary.
1- The first line should give a good description of the commit
2- Avoid long lines (reading truncated commit messages is painful)
Other than that I think it's all common sense/good judgment and I'm not attached to a particular writing style or kind of sentences one should make.
But obviously lower case, present tense, no dot, 50 char limit, and usually starting with add/fix/refactor/update/remove is the way to go. ;)
The first line is special for a reason, it makes shortlog clean and clear.
Does something like that exist?
<action>: <brief explanation>
For example like this:
"refactor: tightened for() loop in networking code"
"added: feature #134"
"removed: debug cruft"
"fixed: one-off bug in string parser"
Could be because of I am new to git
Most tools only shows first line of message. Rest of the message can contain whatever you want.
[jlouis@lady-of-pain ~]$ cat .gitconfig | grep phk
phk = commit -a -m 'upd'The other reason I have it is that when you are first building up a piece of software, you may want to snapshot it now and then, but you don't care too much for the archeology because things are still not working. Once you reach something which seems to work, you squash everything down and cut your first release with a meaningful commit.
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messa...
Strong disagree with antirez on this one. Even vim filetype gitcommit disagrees. (Try it on the "smart synopsis" example.)
But then, I don't understand the distinction the original post seems to be making between "titles or subjects" and "synopses." A good title or subject for a git commit is a synopsis of the changes in the commit, in the same way a good headline for a newspaper article is a synopsis of the article.
The whole thing is serious bikeshedding in my opinion.