What's missing from our changelogs [LWN.net]

What's missing from our changelogs

Posted Jul 25, 2013 1:00 UTC (Thu) by apoelstra (subscriber, #75205)
In reply to: What's missing from our changelogs by corbet
Parent article: What's missing from our changelogs

> 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.)

to post comments

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.