Commit messages are not titles (2015)

76 点作者 arkadiytehgraet超过 5 年前

12 条评论

Commit messages are whatever an individual, community, or organization decides they should be. Debating beyond that is like debating tabs vs spaces. It doesn't matter as long as everyone you're working with is on the same page.

评论 #21831687 未加载

评论 #21831451 未加载

评论 #21835421 未加载

评论 #21831066 未加载

评论 #21831119 未加载

评论 #21832327 未加载

评论 #21831662 未加载

评论 #21832537 未加载

awolf超过 5 年前

> If the first line of a commit message is a title, it changes the way you write it. It becomes just some text to introduce some more text, without any stress on the information density.I agree with the author that commit messages should optimize for information density. However the example they provide does a poor job of this:> This is a smart synopsis, as information dense as possible."This is a" is the type of thing that should never appear in a commit message as it could apply to EVERY commit message. Synopsizing is the action, but doesn't indicate what is being synopsized; one of the most important facts for someone to understand what is happening here. Finally "as information dense as possible", again should also be cut as this is telling us HOW not WHAT (and ironically hurts information density).Were I writing this example it would be:<pre><code> Synopsize how to write a commit message </code></pre> ---I led an initiative at my current company to enforce all commit messages start with an imperative verb and be less than 72 characters. Some people hate it, some people love it.Aside from standardization, the primary reason to do this is the imperative mood leads to the most concise sentence possible. By leading with the action, the most natural thing to do next is to talk about what is being acted upon. Unnecessary words are dropped and the most important facts are emphasized. In short it forces the author to get to the point.<pre><code> [Act] upon [some aspect of the code] </code></pre> e.g.<pre><code> Add user login link on home screen Refactor authentication into separate classes Lint PR titles conform to standard format</code></pre>

评论 #21831534 未加载

评论 #21831528 未加载

评论 #21833786 未加载

评论 #21832296 未加载

评论 #21831573 未加载

评论 #21832813 未加载

st_goliath超过 5 年前

There is probably no reasonable, generic guide on how to write commit messages, since different communities use git in different ways. So IMO this article is comparable to a discussion about indentation styles or text editors.> Commit messages are not titles> Nor subjects, for what matters.> ...> however many times there is no body, there is just the first line.In Linux (the Kernel) development (where git actually came from), commits are sent as patches via e-mail to mailing list for review and for maintainers to pick them up.The first line from the commit message becomes the subject line, the rest of the commit message and the diff becomes the body of the mail. The commit message should briefly explain why you are doing this, the what should be mostly in the diff itself. Having no body text after the first line for a non-trivial patch would be rather bad practice. Obviously the author of this article comes from a different background.But then again, in different communities, a concise single line description with a ticket number may be enough.

mceachen超过 5 年前

Capturing the reason why something was changed, why this approach was chosen, and possibly enumerating other approaches not taken (and why they weren't picked), are all gold to the Engineers of Tomorrow spelunking into some codebase.Summarizing a diff frequently doesn't add information that the diff itself already includes. Title or no title.I'm surprised we don't think about how to shout into the future more effectively. It might be ourselves that we're helping the most.

评论 #21833399 未加载

sovietcattle超过 5 年前

Trying to impose "one way" to write commit messages is silly at best.At work I follow whatever convention the team I'm on agrees with.For my projects I use commit messages as a way to "tag" changes, more than to explain the changes using prose. That way it's very easy for me to search for changes in the codebase.eg. #event-loop #fix #multiple-dispatch #repeated-message (remove the # and you get the idea)

thrower123超过 5 年前

Most commit messages look like this:<pre><code> #1234 fixed the fucking fooinater that wouldn't frobulate. </code></pre> Thank god for the hash ticket number linking standard. Unless you are working on the kernel, your context and discussions and notes are in the bugtracker, so there's no very good reason to write an essay in the commit log.

评论 #21831589 未加载

mcguire超过 5 年前

The first comment:"Every source control management system has its own rules. So what I say here for Git might not be valid for Mercurial, SVN, Bazaar, ..."Git has a wonderful tool named format-patch, <a href="http://git-scm.com/docs/git..." rel="nofollow">http://git-scm.com/docs/git...</a>, that takes a commit and converts it to an email, to put it in a nutshell. Why is there a tool for that? Because Git was created to manage Linux kernel development, and that is done in most parts in or around the Linux Kernel Mailing List. So, the entanglement between commits and emails is deep rooted in Git. And yes, the first line of the commit message _is_ used as the subject."This explains, why you can google "git commit message" and find the same advice over and over again:"<a href="http://git-scm.com/docs/git...*" rel="nofollow">http://git-scm.com/docs/git...*</a> "<a href="https://github.com/erlang/o...*" rel="nofollow">https://github.com/erlang/o...*</a> "<a href="http://tbaggery.com/2008/04...*" rel="nofollow">http://tbaggery.com/2008/04...*</a>""No dot at the end, because it might end up as email subject, also use 50 chars or less."*"I agree, that interpreting it as title for a longer commit message is a bad idea. The conciseness of this line is something important to be retained. A well-crafted email subject on the other hand makes in some cases reading the whole email unnecessary or only complimentary. (Yes, such things exist.) And that are the types of commit messages that we should strive for, ending with a dot or not."

dang超过 5 年前

Discussed at the time: <a href="https://news.ycombinator.com/item?id=9763463" rel="nofollow">https://news.ycombinator.com/item?id=9763463</a>

boomka超过 5 年前

Best practice advice used to be "dont leave your commit message empty" and now it seems headed in a direction of some kind of storytelling guide. Up next: the role of character development in your commit messages

评论 #21833892 未加载

xwdv超过 5 年前

Commit messages are not titles, or subjects, they are COMMANDS, written in the present tense, that describe exactly what will be done to the codebase if you merge in the commit. That’s pretty much all there is to say about it.

评论 #21831148 未加载

mc3超过 5 年前

Just use {JIRA Reference} - {JIRA title} and get on with your life.

评论 #21831288 未加载

gumby超过 5 年前

Why should a message subject not end with a period?