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 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."
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).)
Regardless of whether commit messages are in past or present tense, have trailing period or not, properly capitalized or not -- they are all equally unreadable with all the "Merge pull request #20552 from jamesdabbs/belongs-to-polymorphic-force-reload" junk.
Yeah, that's something that I never understood. The most important information is not that this is a merge, but the intent of the branch. You can give extra detail in the extended part, but the title should not be just referencing the way in which those changes found their way to the branch, and not what they do as in the rest of commits...
I believe Github lets one add extended commit messages for merge commits. Most of us (including me) tend to ignore that and use the autogenerated one. It'd be nice if we had an easy option to automatically include the PR's description (first comment) as the merge commit's message.
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.
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.
For serious. For just one example, `cat` doesn't act as expected without a trailing newline. You end up with stuff like <(echo) to space things out and it's really bogus.
> "If it's open source you can fix it yourself, given that it is not standardised somehow, and that you have time to spare, and that you have the skills and knowhow to do it or that you possess the financial resources to hire some developers to do it for you.
I am glad to see your comment. I wanted to post 'Who cares?' Not about commit messages, because having nice compact descriptive messages can be useful, but mostly about the 'dot' at the end. Because seriously; 'Who cares?'
Bikeshedding like this is useful as a team efficiency metric.
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)
Well that's the point. Feed the team with a trivial problem to see how they react.
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.
What is it about our industry (or perhaps just the slice of it that hangs around HN) that makes people feel the need to spout absolutist dogma about trivial shit like whether a commit message should be a sentence or not? Jesus. Sometimes a sentence is the most useful and sometimes a very short newspaper-headline-style summary is the most useful. Why must we constantly go in search of hard rules that prevent this sort of consideration? If having to shift between styles makes commit logs too hard to read for you, maybe the commit messages aren't the problem.
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.
It does affect readability! That's the reason we have punctuation rules in human languages.
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.
Its defensible to adopt an abbreviated style suitable for the context of oneliner commits in a long report. Nobody uses natural language when creating other textual reports like that - e.g. log messages, checkbook register, ships' log. They all have an encoded style unrelated to natural language.
Also, even if it doesn't affect you, that is completely irrelevant for the project. A project should be oblivious to any one developer's preferences. Successful software projects thrive on conventions that affect the whole project. People do what's implicitly or explicitly agreed on, a person can't just ignore rules he doesn't see the value of.
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).
A project can't be completely oblivious to preferences. You'll never find something that everyone agrees on. Eventually you have to pick something that's acceptable to the majority of the people working on the project and move on.
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.
I've never seen a project use commit messages with periods and I've never felt like it affected readability at all. I don't think it really has anything to do with natural language style conventions. Writing a paragraph consisting of several sentences is very different from a disjoint set of statements which I have always seen separated by newlines anyway.
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 :)
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.
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.
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.
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.
When using Git's mail features -- remember, not everyone uses GitHub -- the first line of a commit is a subject line. It's good practice to just think of it that way. If you write sentences in your subject lines in e-mail, I guess, that's up to you. Don't take it from me, read the Tim Pope counterpoint, with eight extremely good reasons for concise subjects in the closing paragraph:
I don't see how this is a counterpoint. tpope says "This first line should be a concise summary of the changes introduced by the commit", and antirez says the first line should be a "synopsis of the meaning of the change operated by the commit"; these appear to be exactly the same thing.
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 50 character limit on the first line of a commit message really bugs me. I try to stay within 50 characters but sometimes I don't care. I can't always fit what I want in 50 chars and adding a second line can be too much. This is the worst kind of thing around tooling, these types of conventions, in this case because that's how Torvald's wants kernel git commits formatted. I am not committing to anything Torvald's cares about.
I've seen a lot of posts and comments about the 50 character convention but I'm not sure I've ever seen a reason for that specific number. What is the reason for that anyway?
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 ;-)
> 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.
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.
From a code standpoint (excluding commit messages) DVCSes tend to do a better job at expressing high quality history. As an example you have two ways to express a merging history (merge and rebase), giving the developer more tools to accurately describe what has historically happened.
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).
It really depends on the situation tbf; if you're looking for a commit or an overview of what happened, titles; if you're looking for details, especially important in the less legible languages and environments (C, the Linux kernel), body.
Body is super important, but when you can craft a very good single line commit message, is not bad either. It is hard to find a balance but what I try to do is to reserve multi line commit messages for situations where it is appropriate to provide mode details compared to just "git show" the commit to check the actual content.
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 think 80% of the commits in this current project have the word "fix" in it. I hate that word. Doesnt say or mean anything anymore, hardly ever did.
To improve a teams or organizations commit messages, perhaps we should instill an organization/team-wide ban on certain words, such as fix, and bug. How can more than 50% of a development project be bugs and fixes? Dafuq.
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.
With the 'what' of course I don't mean 'what happened', as the latter would be actually kind of the 'why' you're making the change. So with the 'what' I mean 'what is being changed', some people just write what file are changing and what they are adding to it, explaining how the code is changing in the diff, but not why the code is changing.
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".
I have no objection to summary comments - they can guard against certain types of accidental or otherwise erroneous edits. If the code and the comment don't quite agree then suspect both of them are wrong.
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.
Yeah, the legacy project I'm working on isn't that modern... And even when rules are enforced, people sometimes work around them and leave a useless commit comment. Lax documentation, sometimes deliberately lax, is a person problem unfortuntely - one better solved in ways that HR would disaprove of then via technical blocks!
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?
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.
How can anyone take the author's word on whether or not to put a full stop at the end of something when he puts a full stop at the end of the bullet points in his list? That's far worse usage than anything he's doing in the title/summary/smart synopsis. https://www.oxforddictionaries.com/words/bullet-points
> 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.
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.
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.
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.
By that logic we should also take into account all the other 1000s pieces of technology that can operate with text. In the end it all comes down to personal preference or the project guidelines.
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.
> 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.
Honestly those commits should probably be split anyway. A commit should represent the smallest 'change' which is singificant.
>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.
I struggle to see how this adds so much more effort?
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 can't imagine my workflow being all that special, but I never have to deal with this?
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.
I did this too in the past, but I've since found the convenience of 'git gui' too hard to ignore. The fact that it seamlessly runs on remote servers over X forwarding without having to install anything on the remote server really helps.
> 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".
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.
Adding a new feature is the main reason you'd want to refactor something. Refactoring for its own sake is nice in theory, but ain't nobody got time for that. If you are doing real refactoring in a practical setting, it's probably a situation like adding a feature that closely parallels an existing one and now some of the stuff the old feature does can be factored out.
Refactoring is often done in order to implement a new feature, but that doesn't mean they need to be done in the same commit. A common workflow is to be implementing something, realize a refactor is needed, "git stash", refactor, commit, "git stash pop", continue feature work.
- 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 :) )
Yeah, that's why I really hate rules like "all commits must have a user story attached". I'm not going to make a jira story for "function is poorly named", so if that's the rule then the code will fall to entropy.
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!
Every newspaper -- even ones that mostly use AP style -- has its own slightly different style guide. I don't think that proves style guides are pointless.
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.
So very true. And I struggle with this. "Why should I write something out when tools could do it for me? Isn't me specifying it, then, just me being overly verbose?" But tools often don't - and may never.
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.)
Github has a way of linking issues with commits. You just mention the issue in the commit e.g. 'This commit closes #1' and i believe the issue will close with that as well, but it will show up in the issue.
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
Our internal system has some integration between Jira and Github, such that if you comment a commit with the ticket number then you can see them all in the Jira ticket.
Not exactly. The actual commit content is in the code difference. Code message is just some kind of human-readable abstract, or at least - a hit of what was changed.
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), ...).
Great observation, though it's not a bad thing, necessarily (assuming you were even implying that it was).
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.
While I commend the poster's ideals, the method only works in the glass cathedrals model of development. One in which no commit gets made without having followed the process from inception, through requirements gathering, through unpressured development, through appropriate and thorough QA/code review, and deployment. In the street market bazzar you're left with thousands of micro commits that you don't have time to sit down and create an illuminated manuscript page for each commit explaining it's small description, and it's naritive history.
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.
Does phk mean what I think it means? It's definitely funny and I'd definitely decline all your pull requests, but in company work it really doesn't matter because most people don't look into the history anyway. So yeah, it's probably a productivity tip.
It pays eternal homage to a toy-repository by phk in which that commit message occurs. I found it more fun than `git yolo`. And easier to type as well.
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.
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.
We use Redmine and just put the relevant issue number and the title of the issue. If more information is needed, you can go to Redmine to check more details or how to reproduce.
I prefer the next step over: Branch is named after the ticket and a short description of what the branch does, commit messages just talk about the contents of the commit itself.
We actually don't make a branch for each ticket because we need to expose the repositories to outside and so we use Gitolite, and having to reconfigure branch permissions each time... Ain't nobody got time for that.
172 comments
[ 3.2 ms ] story [ 153 ms ] threadI 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?
https://news.ycombinator.com/newsguidelines.html
1)
2)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.
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
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.
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.
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.
Actually TL;DR both are important.
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. ;)
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 think 80% of the commits in this current project have the word "fix" in it. I hate that word. Doesnt say or mean anything anymore, hardly ever did.
To improve a teams or organizations commit messages, perhaps we should instill an organization/team-wide ban on certain words, such as fix, and bug. How can more than 50% of a development project be bugs and fixes? Dafuq.
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.
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.
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 ought to consist of a title, followed by an empty line and a short(-ish) summary.
The whole thing is serious bikeshedding in my opinion.
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-...
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
Most tools only shows first line of message. Rest of the message can contain whatever you want.
> <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.
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 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.
However, pretending there is a one-size-fits-all rule is taking it too far.
Could be because of I am new to git