User: Password:
Subscribe / Log in / New account

In search of the perfect changelog (Impact:)

In search of the perfect changelog (Impact:)

Posted Apr 30, 2009 11:53 UTC (Thu) by Duncan (guest, #6647)
Parent article: In search of the perfect changelog

Having seen several Impact: lines (now that they're at the bottom with the
signoffs and etc) in the mainline changelogs of late, I can say one thing
for sure -- they've DEFINITELY improved changelog usability here.

I don't claim to be a C coder let alone a kernel coder. Computing and
therefore Linux is a hobby for me, not a job, so I'm not a pro, either.
Despite that, I take seriously the responsibility of being the sysadmin on
my own systems. As such, I like to have at least a general idea of what
sort of changes are happening in both kernel and userspace and spend quite
some time keeping track of such things.

As such I'm no stranger to kernel changelogs altho I don't pretend to
understand even the half of them. I still like to think they help me
follow the general trends, etc, and I know I've certainly been able to
help not only myself but others based on it. But while many of the the
titles and descriptions "are Greek to me", those Impact: lines I normally
CAN understand. It makes my job as an admin, NOT a coder, vastly easier,
because unlike much of the rest of the changelog, the Impact: lines tend
to be close enough to "sysadmin dialect English", as opposed to "kernel
hacker dialect English", that they actually make sense.

Additionally, with the Impact statements now at the end, the effect of the
overall format is the same thing composition teachers have been teaching
for years. "Tell them what you are going to tell them, tell it, then tell
them what you told them." That's pretty much what the changelog order
does now, beginning with a one-line title/summary, followed by a detailed
explanation, then ending with the practical effect it'll have and
finishing off with the "rolling of the credits". There's a reason that
format is so familiar in papers, etc. -- it "just works". =:^)

So I really like seeing the Impact lines at the end of the description and
hope it becomes standard practice, just like sign-off-by, etc. It really
DOES make a difference. =:^)


(Log in to post comments)

Copyright © 2018, Eklektix, Inc.
Comments and public postings are copyrighted by their creators.
Linux is a registered trademark of Linus Torvalds