Dear Peter Tyser,
In message 1273075406.2451.4225.camel@localhost.localdomain you wrote:
Could you describe what you use CHANGELOG for? I often look at logs, but 99% of the time its a log of a specific file or directory to trace a bug, see why feature X was added, etc. I rarely look at the repositories entire log, and if I do, I use 'git log'. Although 'git log' takes longer, its guaranteed to be accurate, unlike CHANGELOG which may be slightly out of date.
Most frequently I use it in combination with some form of grep command (grep, agrep etc.); sometimes I use it in vi/view for manual searching / reading.
Here are a few reasons where I prefer accessing the CHANGELOG over running "git log --grep":
1) it's faster:
-> time grep foobar CHANGELOG
real 0m0.005s user 0m0.004s sys 0m0.001s
-> time git log --grep=foobar >/dev/null
real 0m0.240s user 0m0.219s sys 0m0.021s
2) it's more efficient:
-> strace -f grep foobar CHANGELOG 2>&1 >/dev/null | wc -l 143 -> strace -f git log --grep=foobar 2>&1 >/dev/null | wc -l 2494
3) it delivers only the lines I cactually search for, while "git log --grep" always spills out the whole commit message:
-> grep MPC512x CHANGELOG | wc -l 24 -> git log --grep=MPC512x | wc -l 272
4) I can use arbitrary grep options. I am not aware of a git equivalent to, say:
-> grep -C2 --color string CHANGELOG
5) I can use other tools to process the messages, like agrep for fuzzy searching; I frequently use this when checking if a specific patch has been applied - too many times a plain text search does not work because the committer manually edited the commit message to fix typos etc. I am not aware of a git equivalent to, say:
-> agrep -2 -i string CHANGELOG
This is probably my most frequently used command
If you do prefer the speed of looking at a CHANGELOG file, its easy to generate one when you require it.
Yes, I know. But I also want it available to those who don't use git, so it should to be included in the release tarball, and in the auto-generated tarballs when using the "snapshot" links on the web interface; for example try:
-> wget -O u-boot.tgz 'http://git.denx.de/?p=u-boot.git;a=snapshot;sf=tgz'
Does it hurt you?
'hurt' is a strong word, but it certainly annoys me too. Eg:
- Every time someone greps they have to visually ignore the CHANGELOG
file hits, or alternately make a grep wrapper script specific to u-boot that strips out CHANGELOG hits.
Strange. If I ever run into such a problem then so infrequently that I don't notice it. I guess this is because I usually only grep in specific file types (like "*.[Sch]" or so).
- Its a duplication of data that's already stored in the repository
history. Who likes duplicated data?
In the strict sense, all the checked out files are duplicated data.
- For any change that is automated via a script/grep/sed/etc one needs
to filter out the CHANGELOG files.
You probably need to exclude a number of other files as well?
We could also follow Linux's lead and upload the CHANGELOG as a separate file from the source. eg there would be a CHANGELOG-{V} for each released U-Boot version detailing only what changed since the last release (www.kernel.org/pub/linux/kernel/v2.6/), or alternatively one mega-CHANGELOG like we're doing now if people prefer.
I would like to keep the CHANGELOG as part of tarballs, including auto-generated ones.
Best regards,
Wolfgang Denk