Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Commit messages are not titles (2015)

antirez.com

Post reply on HN
Print view View original

31–40 of 58 posts

Re: Commit messages are not titles (2015)

#31

Post by brigandish »

brian_cunnie wrote: post #23
ticmasta wrote: post #8

Earlier quoted context omitted.

Well, I'll say more... They are a summary of what will happen if the commit (which is a bunch of commands) is applied. They also can elaborate on the context around the commit. It's thoughtful of the commiter if your coworkers don't need to dive into the detailed changes to get a broad picture of why the commit exists.

This. Also, commit messages are sometimes the "documentation of last resort". In my organization, putting comments in the code is frowned upon. "Comments are lies! The documentation is in the tests!" But the tests don't lend themselves to _reasons_ behind why the code was written a certain way, why a given approach was taken (for example, we needed to re-write a Rails database migration in a somewhat contorted manner…

The why is the thing most often missing from documentation of any sort. I often find myself looking at the README for a library I've not heard of and wondering what it will do for me because it only states the what, the why often tells me the/a problem the library solves.

> Foobar packs JSON into binary

vs

> Our Rest API was slow and bandwidth heavy, so we wrote a library (Foobar) that packs JSON into a binary format. Now our messages are 50% smaller and 30% faster.

Git commit messages are worse offenders but there's plenty of criminals about!

Re: Commit messages are not titles (2015)

#32

Post by jangid »

caseymarquis wrote: post #4

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.

Agree. In one group, I have to put title (summary) in one line and that's it. In Emacs, we have a title in the first line and then bulleted (*) summary for each file in the changeset. See http://git.savannah.gnu.org/cgit/emacs.git/commit/. I prefer the later. But that is not always possible.

Re: Commit messages are not titles (2015)

#33

Post by lmm »

protonimitate wrote: post #22
caseymarquis wrote: post #4

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.

The "rule" I like when it comes to commit messages it that they should be clear enough that someone who gets woken up for a production issue at 3am can quickly parse what was in the commit and how dangerous it is. Nothings worse than digging through a ton of diffs to find the breaking change.

I find that requiring "nice" commit messages tends to mean digging through bigger diffs to find the breaking change. If you're fine with commit messages like "fix" or "derp", then people are more willing to make each tiny change a separate commit, and then a git bisect takes you right to the specific diff that caused the problem.

Re: Commit messages are not titles (2015)

#34

Post by AlexCoventry »

awolf wrote: post #6

> 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…

> all commit messages start with an imperative verb and be less than 72 characters

Just the first line, right?

Re: Commit messages are not titles (2015)

#35

Post by em-bee »

lmm wrote: post #33
protonimitate wrote: post #22

Earlier quoted context omitted.

The "rule" I like when it comes to commit messages it that they should be clear enough that someone who gets woken up for a production issue at 3am can quickly parse what was in the commit and how dangerous it is. Nothings worse than digging through a ton of diffs to find the breaking change.

I find that requiring "nice" commit messages tends to mean digging through bigger diffs to find the breaking change. If you're fine with commit messages like "fix" or "derp", then people are more willing to make each tiny change a separate commit, and then a git bisect takes you right to the specific diff that caused the problem.

that is an interesting argument, but i don't quite buy it.

the commit history is used for other things too, not just to find bugs using bisect. if that was the case we would not need any commit messages in the first place.

how much effort does it take to explain the change in a sentence? if it is a small change then it also will be a small commit message.

the commit message doesn't need to be nice, but it should be descriptive.

Re: Commit messages are not titles (2015)

#36

Post by em-bee »

beatgammit wrote: post #24
protonimitate wrote: post #22

Earlier quoted context omitted.

The "rule" I like when it comes to commit messages it that they should be clear enough that someone who gets woken up for a production issue at 3am can quickly parse what was in the commit and how dangerous it is. Nothings worse than digging through a ton of diffs to find the breaking change.

Yup. I follow the kernel commit message guide, since it seems pretty reasonable. It's basically: 1. really short summary in a few words, ideally mentioning the relevant issue(s) in the bug tracker 2. Blank line 3. Longer message, if necessary, to explain the change If I'm going to be looking back through commit messages, that's the type of commit message I want to read. I want to know whether this commit is interesti…

another use for commit messages is to document learning.

when we figured out how to avoid a certain type error in typescript, we made sure to describe it in a way that we would find it again, or it would come up in a search.

Re: Commit messages are not titles (2015)

#37

Post by awolf »

AlexCoventry wrote: post #34
awolf wrote: post #6

> 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…

> all commit messages start with an imperative verb and be less than 72 characters Just the first line, right?

yes

Re: Commit messages are not titles (2015)

#38

Post by awolf »

bagacrap wrote: post #27
awolf wrote: post #6

> 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…

I've literally never heard or read the word synopsize so I'd get stuck there wondering what the heck was happening. Try "summarize".

sure, was just matching what the author said in their example. 100% agree no need to use obscure words

Re: Commit messages are not titles (2015)

#39

Post by Already__Taken »

duxup wrote: post #13
caseymarquis wrote: post #4

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.

Seriously, in an interview I was asked about some misc code formatting preferences. At home I use whatever prettier decides. At work I just want to do what everyone else is doing so that we are on the same page. Maybe it is weird or something, I really don't care. More important we all work together.

If AI can write news articles these days I wonder if the actual answer is what you wrote. Build a commit parser into version control to auto-write the titles for you. All you do is write a good message. Prettier but for commit messages.

Re: Commit messages are not titles (2015)

#40

Post by kzzzznot »

mceachen wrote: post #29

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 effec…

I think capTuring the “why” of a commit is often overlooked but highly valuable.
Post reply on HN