What's missing from our changelogs

Posted Jul 24, 2013 22:28 UTC (Wed) by ebiederm (subscriber, #35028)
Parent article: What's missing from our changelogs

There are also times when you make trivial patches that the subject line is all you need to describe the change.

I respectfully suggest your measurement and conclusions are in error.

You did not measure if the what was written actually describes what is going on, and without actually looking to see if the subject is sufficient explanation it is quite insulting to call some of these patches no explanation patches.

You seem to be encouraging people to make larger harder to bisect and harder to read patches simply to get get patches that need more explanation. Something I expect would be much worse.

What's missing from our changelogs

Posted Jul 24, 2013 22:41 UTC (Wed) by nix (subscriber, #2304) [Link]

A huge number of Al's changes, for one, are just a result of splitting up interface changes to the VFS per-filesystem. There's really not much to say about all the changes after the one that makes the actual VFS changes (though a link back to the SHA-1 ID of that in each filesystem-specific change might be good).

What's missing from our changelogs

Posted Jul 24, 2013 22:42 UTC (Wed) by corbet (editor, #1) [Link] (3 responses)

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