When Linus made his switch to BitKeeper for maintaining the kernel source tree, the format of his changelogs also changed. Linus himself at one point commented that simplifying the changelog was on his todo list, however many spoke out in support of the newer, more verbose logs. They have since been the standard. Find an example of the old style here, and the new style here.

The question of readability came up on the lkml recently, Ian Molton saying, "I dont know who to write to about this, but the changelogs for 2.4.19-pre on kernel.org are COMPLETELY illegible." He went on to suggest that the logs be tweaked a little. Linus agreed that the logs could be improved, and put out a call to Perl scripters to help with the change. Some of the discussion follows, as well as a link to the thread in online archives.

From: Ian Molton
Subject: Changelogs on kernel.org
Date: Sun, 12 May 2002 01:07:09 +0100

Hi.

I dont know who to write to about this, but the changelogs for
2.4.19-pre on kernel.org are COMPLETELY illegible.

Can we 'tweak' them so that instead of:

[email filtered] (02/04/17 1.383.12.1)
	Fix meye driver request_irq bug.

[email filtered] (02/04/17 1.383.12.2)
	Enable the meye driver to get parameters on the kernel command line.

[email filtered] (02/04/17 1.383.13.1)
	[PATCH] add __LINE__ to out_of_line_bug()

[email filtered] (02/04/17 1.383.13.2)
	[PATCH] PATCH: some configure.help updates

[email filtered] (02/04/17 1.383.13.3)
	[PATCH] PATCH: more configure.help

[email filtered] (02/04/17 1.383.13.4)
	[PATCH] PATCH: More configure.help

[email filtered] (02/04/17 1.383.13.5)
	[PATCH] PATCH: more Configure.help

[email filtered] (02/04/17 1.383.13.6)
	[PATCH] PATCH: maintainers update

[email filtered] (02/04/17 1.383.13.7)
	[PATCH] PATCH: make cpu names clearer for new VIA

We get something nice like:

[email filtered]
   Fix meye driver request_irq bug.
   Enable the meye driver to get parameters on the kernel command line.

[email filtered]
   [PATCH] add __LINE__ to out_of_line_bug()

[email filtered]
   [PATCH] PATCH: some configure.help updates
   [PATCH] PATCH: more configure.help
   ... above repeated 2 times
   [PATCH] PATCH: maintainers update
   [PATCH] PATCH: make cpu names clearer for new VIA

From: Linus Torvalds
Subject: Re: Changelogs on kernel.org
Date: Sun, 12 May 2002 20:06:39 +0000 (UTC)

Ian Molton wrote:
>I dont know who to write to about this, but the changelogs for
>2.4.19-pre on kernel.org are COMPLETELY illegible.

Hmm..

You're definitely right about the BK version numbers, since those are
meaningless anyway (they are only meaningful within one BK tree, and
they change over time when you merge different trees together.

The 2.4.x changelogs seem to be done with my "release" scripts, but
additionally they don't have the same kind of detailed information that
the 2.5.x kernels have, and yes, the result is fairly ugly.

What are peoples opinion about the "full" changelog format that v2.5.x
kernels have? Should we sort that too by author?

Perl is the obvious choice for doing transformations like these. Is
anybody willing to write a perl script that does the "sort by author"
thing?

I'll remove the date/BK ID thing, so that my unsorted changelogs would
look like the appended thing. But yes, sorting (and merging) by author
would probably be a good thing. (My BK changelog scripts can also add
markers around the actual log message, to make parsing easier).

Linus

From: Jeff Garzik
Subject: Re: Changelogs on kernel.org
Date: Sun, 12 May 2002 16:20:05 -0400

Sorting might help a tiny bit...

I thought about this, when I saw the 2.4.x changelogs. Typical GNU
projects seem to have a pretty decent system going -- there is a
detailed ChangeLog, and an abbreviated high level summary NEWS, for each
release.

So IMO a good solution would not be to change the format of the BK
changelogs, but to supplement them with the type of summary that looks
like the "old Linus" changelogs, i.e. a summary generated by a human:

    Martin Dalecki - IDE updates
    Al Viro - VFS updates
    Andi Kleen - x86-64 update
    ...

The central complaint about BK changelogs seems to be that they are too
verbose for a quick scan of what a new kernel version contains. (while
at the same time lauding the additional information BK provides over the
old changelogs)

Marcelo gave it a good shot, by (it appears) generating a summary by
taking the first line of each cset. The better solution would be a
human-generated NEWS file.

Jeff

From: Dr. David Alan Gilbert
Subject: Re: Changelogs on kernel.org
Date: Sun, 12 May 2002 21:31:03 +0100

> Linus Torvalds wrote:

> What are peoples opinion about the "full" changelog format that v2.5.x
> kernels have? Should we sort that too by author?

I used to read the hand written changelogs, they only used to be a half
page or so; neatly summerising stuff into one line; I can't be bothered
with the full changelogs - they are obviously useful; but the hand
written half pages are still a lot easier at a quick glance to see if
there is anything that affects you.

Perhaps insisting that each check in message includes a single line (sub
60 chars) description; could turn those into description : name and
remove dupes?

Dave

From: Linus Torvalds
Subject: Re: Changelogs on kernel.org
Date: Sun, 12 May 2002 18:56:34 -0700 (PDT)

Yeah, I know. Some people like the long ones, though, and they _are_
useful if you want to get a more detailed view.

I definitely don't want to maintain a separate set of short logs, but the
answer may be to just do both: have the existing long log (with no merging
of changesets, so that people see the actual commit boundaries), and a
separate "short" version that also merges the thing.

As an example, if the long version looks like this:

	[email filtered]
	        A bunch of fixes.

	[email filtered]
	        Pmac updates

	[email filtered]
	        Some more small fixes.

	[email filtered]
	        [PATCH] 2.5.13: vmalloc link failure

	        The following patch fixes this, and also fixes the similar
problem in
	        scsi_debug.c:
	...

The short version could look like

	[email filtered]:
		A bunch of fixes.
		Pmac updates
		Some more small fixes.

	[email filtered]:
		[PATCH] 2.5.13: vmalloc link failure


	...

ie only take the first line, and merge entries with the same author.

Perl people, stand up.

Linus

---

Many Perl scripts have been offered, many of which can be found online in an lkml archive. I look forward to the new, easier to read format.