Weekly edition	Kernel	Security	Distributions	Contact Us	Search
Archives	Calendar	Subscribe	Write for LWN	LWN.net FAQ	Sponsors

In search of the perfect changelog

Posted Apr 23, 2009 22:22 UTC (Thu) by vomlehn (subscriber, #45588)
Parent article: In search of the perfect changelog

"most developers simply lack the writing skills needed to write clear and concise changelogs. ... [M]ost developers can, at least, be trained to write a reasonable impact tag.

*sigh*

Counter to intuition, I understand from a number of people who write for a living, as well as from personal experience, that it is a good deal harder to write something short than something long. Usefully capturing the important details of a patch in a single line is *much* harder than explaining what it does in a couple of paragraphs. Encouraging single-line changelogs scares me.

(Log in to post comments)

In search of the perfect changelog

Posted Apr 24, 2009 2:57 UTC (Fri) by nevets (subscriber, #11875) [Link]

The Impact line is not a replacement for a change log, it is simply the reason for the patch.

Well, that is the way I prefer to think of it. When Ingo asked me to start including Impact lines, I struggled with it. I'm guilty of doing the

Impact: cleanup

that Linus complained about. Because, really, that is useless. But trying to come up with an "Impact" for the patch I found very difficult. But now I think of it more as the reason for the patch, not what the patch actually does. This is the typical changelog I submit:

Subject: ....

Detail description of the what the patch does.

[ Impact: what is the purpose of the patch. ]

Signed-off-by: ....

Here's an example:

ring-buffer: only warn on wrap if buffer is bigger than two pages

On boot up, to save memory, ftrace allocates the minimum buffer
which is two pages. Ftrace also goes through a series of tests
(when configured) on boot up. These tests can fill up a page within
a single interrupt.

The ring buffer also has a WARN_ON when it detects that the buffer was
completely filled within a single commit (other commits are allowed to
be nested).

Combine the small buffer on start up, with the tests that can fill more
than a single page within an interrupt, this can trigger the WARN_ON.

This patch makes the WARN_ON only happen when the ring buffer consists
of more than two pages.

[ Impact: prevent false WARN_ON in ftrace startup tests ]

The subject and description describe what the patch does. The description may even go into detail of the history that caused this patch. But the Impact line is simply a one liner summary of the purpose of the patch.

In search of the perfect changelog

Posted Apr 24, 2009 14:19 UTC (Fri) by jlokier (guest, #52227) [Link]

If that's what Impact: means, it really should have been Purpose:.

Impact means "what does this cause" or "what does this effect",
not "what is this for".

I suspect if Ingo had used Purpose: there might have been little or no objection.

In search of the perfect changelog

Posted Apr 24, 2009 14:36 UTC (Fri) by nevets (subscriber, #11875) [Link]

That is what I take as the meaning of Impact. It is not what Ingo told me. There's a fine line between "Impact" and "Purpose". And although I view it as the purpose of the patch, the line itself does show an impact of the patch. But to find the Impact, I must first look for the purpose.

I can say, the impact of that patch is the prevention of false warn ons. There is a very subtle difference between the two.

In search of the perfect changelog

Posted May 1, 2009 21:54 UTC (Fri) by roelofs (guest, #2599) [Link]

There is a very subtle difference between the two.

One obvious difference is in the case of side effects (either temporary or long-term, e.g., "out-of-tree drivers depending on foobar semantics will no longer work"). In that situation the purpose is one thing, and the impact presumably includes that thing, but it also includes the side effects: i.e., the impact is a superset of the purpose (in such cases).

Greg