What's missing from our changelogs

Posted Jul 24, 2013 22:42 UTC (Wed) by corbet (editor, #1)
In reply to: What's missing from our changelogs by ebiederm
Parent article: What's missing from our changelogs

"No-explanation" means no text in the explanation area; I'm sorry if that wasn't clear.

The article does say that, for some patches, a one-line summary is sufficient.

I'm confused by the comment on readability; the point of the explanation area is to make the patch easier to understand, after all. I didn't suggest populating it from your spam folder. And I'll confess to being totally thrown by the mention of bisectability - how on earth is that affected by changelog contents?

What's missing from our changelogs

Posted Jul 25, 2013 1:00 UTC (Thu) by apoelstra (subscriber, #75205) [Link] (1 responses)

> I'm confused by the comment on readability; the point of the explanation area is to make the patch easier to understand, after all. I didn't suggest populating it from your spam folder. And I'll confess to being totally thrown by the mention of bisectability - how on earth is that affected by changelog contents?

I think the implication was that people ought to keep piling things into a single commit until that commit is complicated enough to justify a full explanation.

Having said that, I read the article and understood it the way you intended. (And I think most developers would have no problem recalling examples of commits where one line is sufficient, even if you had not pointed it out.)

What's missing from our changelogs

Posted Jul 26, 2013 11:58 UTC (Fri) by bfields (subscriber, #19510) [Link]

Or to put it another way: if someone takes a complicated change, carefully splits it into small independent steps, and leaves the explanation on the first commit--then they get dinged for writing inadequate commit messages?

Often the reason Al's patches lack changelog bodies is because he does the hard work of figuring out how to get from point A to point B in trivial self-explanatory steps--something he deserves credit for. (What *does* get lost, I think, is motivation: for example, motivation for the readdir api change ("dealing with ->f_pos races in ->readdir() instances for good") is only in the cover letter, as far as I can tell, not in any changelog or code comment (but I may have missed it, or maybe it's there in changes to problematic filesystems, I didn't check).)

In any case, I don't think we can draw useful conclusions from simple summaries of the commit statistics--careful examination of representative cases would seem more instructive.

What's missing from our changelogs

Posted Jul 25, 2013 19:51 UTC (Thu) by broonie (subscriber, #7078) [Link]

Yeah, this is particularly true for a lot of the patches which Axel Lin submits - I noticed him appearing in those lists but actually his changelogs are generally very high quality, detailed when they have to be but not tediously long when they're obvious.