2008年 5月 5日
Tension in Debian changelogs
Holger Levsen wonders what tense people write their changelogs in. Andrew Pollock feels that his tendancy is past-tense.
Looking back over some of mine, FreeRADIUS from a long time ago, and openjpeg more recently, it appears that my preference is to actually write them as untensed fragments. I think I'm answering the question "What does this change do?" from the perspective of the change. This would make sense, mirroring somewhat the comments I put in dpatches (and the overly verbose names that have been known to occur) which are usually the patch talking about itself in the plural. Unless that's the patch _and_ I talking about ourselves in the plural?
Permalink Last modified 2008年 5月 5日 @ 9:30 am
Russell Coker said,
May 5, 2008 at 6:13 pm
Personally I don’t mind what tense it’s in - just as long as it’s clear and makes sense.
One thing I really hate is when DDs write changelogs with obscure jokes or which reference other changelogs.
Each entry should stand along and be understood by a reasonable person who’s skill level is lower than that of the average DD. Obviously there are people who can just run diff on the code to determine the difference, the changelog is not for their benefit!
TBBle said,
May 7, 2008 at 11:34 am
I agree, the changelogs need to stand alone and useful in the absence of the source or knowledge thereof.
The changelogs probably don’t need to be useful to someone to whom the package is not useful though.
I don’t mind the occasional “{obscure reference} release” comment at the top of a changelog, though. Of course, I have a good reason to think those are fine. I don’t actually use them myself generally.