Re: Modifications of the changelog.
Hi,
On Di, 24 Apr 2012, Ben Finney wrote:
To say it more plainly: Modifying previous changelog entries, while not
prohibited, does break an implicit user expectation. I think that
expectation is reasonable to an extent, and breaking it is costly to the
same extent.
But there are good reasons to do it at some point, like a new
upstream actually fixed some bugs, and it was realized only afterwards.
So I close the bug per email with a version header indicating the
version where it is fixed, and later I change the old changelog
entry
* new upstream release (Closes: )
and add a few more bugs there.
I consider this reasonable, but in general, I agree it is better to
refrain from too wild rewritting of changelog entries.
Best wishes
Norbert
Norbert Preiningpreining@{jaist.ac.jp, logic.at, debian.org}
JAIST, Japan TeX Live Debian Developer
DSA: 0x09C5B094 fp: 14DF 2E6C 0307 BE6D AD76 A9C0 D2BF 4AA3 09C5 B094
DUNCRAGGON (n.)
The name of Charles Bronson's retirement cottage.
--- Douglas Adams, The Meaning of Liff
--
To UNSUBSCRIBE, email to debian-mentors-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20120424054932.gi23...@gamma.logic.tuwien.ac.at
Re: Modifications of the changelog.
Tomasz Muras nexor1...@gmail.com writes: On 04/22/2012 02:48 PM, Bernhard R. Link wrote: * Arno Tölla...@debian.org [120421 11:51]: The whole point of a changelog is a time dependent frozen point of view at your package. Once you released a version of a package, you should consider it untouchable I strongly disagree. First of all, a changelog is there to see what has changed when, i.e. it is a documentation of what important changed where done and when (i.e. which package version) they were done for. There is normally no reason to change older entries as most details get less important over time, but if there is anything importing misleading in them, something important incorrect or something important enough missing, then not correcting the changelog is not acceptable in my eyes. The new changelog should be about what was changed since the version before (that might be some hint that the older changelog was corrected if you prefer), but import changes in the old package should be in the part of the changelog for the old package. I fully agree with Bernhard - basically if there is a good reason to improve old changelog entry, you should do it. I agree (to a point) with both. I believe old changelog entries should not be touched (apart from typo fixes and the like): adding or removing elements from old entries is Bad(tm). There are very few exceptions, when adding or removing an entry from an old changelog is acceptable, and in those cases, these changes should be documented in the new version aswell, so that those who do not follow the packages VCS, will know that an old entry was modified too, and they might wish to have another look at it. Something like * Changelog for $VERSION updated to reflect reality can work for me, as long as there is some indication in the new changelog that the old was modified. But - and I want to stress this - having to modify old changelogs should be a rare exception. -- |8] -- To UNSUBSCRIBE, email to debian-mentors-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/874nsaye50.fsf@algernon.balabit
Re: Modifications of the changelog.
Russ Allbery r...@debian.org writes: Ben Finney ben+deb...@benfinney.id.au writes: [modifying previous changelog entries] breaks the entirely reasonable expectation: that a changelog only ever accumulates entries for the latest release, and nothing in earlier releases has changed since the last time the recipient read them. I think the absolute prohibition takes things a bit too far. Charles Plessy ple...@debian.org writes: What is that expectation for ? I find it dogmatic written like this. I'm not seeing where what I wrote is an absolute prohibition, nor dogmatic. You both read it that way, though, so I apologise for communicating poorly. To say it more plainly: Modifying previous changelog entries, while not prohibited, does break an implicit user expectation. I think that expectation is reasonable to an extent, and breaking it is costly to the same extent. -- \ “Creativity can be a social contribution, but only in so far as | `\ society is free to use the results.” —Richard M. Stallman | _o__) | Ben Finney -- To UNSUBSCRIBE, email to debian-mentors-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/87zka1bt01@benfinney.id.au
Re: Modifications of the changelog.
* Arno Töll a...@debian.org [120421 11:51]: The whole point of a changelog is a time dependent frozen point of view at your package. Once you released a version of a package, you should consider it untouchable I strongly disagree. First of all, a changelog is there to see what has changed when, i.e. it is a documentation of what important changed where done and when (i.e. which package version) they were done for. There is normally no reason to change older entries as most details get less important over time, but if there is anything importing misleading in them, something important incorrect or something important enough missing, then not correcting the changelog is not acceptable in my eyes. The new changelog should be about what was changed since the version before (that might be some hint that the older changelog was corrected if you prefer), but import changes in the old package should be in the part of the changelog for the old package. as it would confuse people _a lot_ if you force them to read a full backlog of changes every time they upgrade because you /could/ have modified more than the latest entry. Exactly the opposite is true in my opinion: If you already have the last package, then the new changelog entry should only contain the changes since then. But if you forgot to mention an important enough change in an older version, and so not advertise that change there, then people might use the wrong version because they get the wrong picture of where which change was done. (When considering switching from package version A to version B, it should be enough to read the the changelog entries A and = B). Generally speaking it may be ok-ish in important cases to change previous entry if you restrict yourself to spelling fixes and formating changes, but it is completely unacceptable [to me, at least] to reformulate entries, add entries, remove entries and such. If an old entry contains wrong information (either things claimed that are not true, or changes missing that might be important, or worded in a way that people to misunderstand) that is about things important enough that a user could be mislead, I'd rather consider it unacceptable to keep the wrong claims or omissions there. There are of course several reason why not modifying old changelogs or rather erring towards not changing it when being unsure is a good idea: - the changelog format attributes each part of a changelog to a person. So modifying them should make sure one does not misrepresent those changes to changelog. (and if a change is small enough that making that clear would make it harder to read usually means it was not important enough to change it anyway). - any change can introduce new bugs, even in documentation. If the changelog was from someone else (or from yourself from long enough ago), one should be sure enough about what one does. (For the thing triggering this whole discussion: That appears to be simply some needless contentless change in a NMU not related to the NMU, so is quite unrelated to the is editing old changelogs acceptable discussion.) Bernhard R. Link -- To UNSUBSCRIBE, email to debian-mentors-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/20120422124855.ga2...@client.brlink.eu
Re: Modifications of the changelog.
On 04/22/2012 02:48 PM, Bernhard R. Link wrote: * Arno Tölla...@debian.org [120421 11:51]: The whole point of a changelog is a time dependent frozen point of view at your package. Once you released a version of a package, you should consider it untouchable I strongly disagree. First of all, a changelog is there to see what has changed when, i.e. it is a documentation of what important changed where done and when (i.e. which package version) they were done for. There is normally no reason to change older entries as most details get less important over time, but if there is anything importing misleading in them, something important incorrect or something important enough missing, then not correcting the changelog is not acceptable in my eyes. The new changelog should be about what was changed since the version before (that might be some hint that the older changelog was corrected if you prefer), but import changes in the old package should be in the part of the changelog for the old package. I fully agree with Bernhard - basically if there is a good reason to improve old changelog entry, you should do it. The idea of freezing in time and possibility to refer to an old, exact version of changelog (or any other file) looks like to job for Version Control software. Tomek -- To UNSUBSCRIBE, email to debian-mentors-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/4f945c40.1080...@gmail.com
Modifications of the changelog.
* Do not modify previous changelog entries, especially not in NMUs. Hi all, are there concrete problems caused by modifying previous changelog entries ? I do it from time to time, of course not when the diff has to be carefully inspected by others as it would be a distraction, and I have not found it causing breakages. Cheers, -- Charles Plessy Tsurumi, Kanagawa, Japan -- To UNSUBSCRIBE, email to debian-mentors-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/20120421073546.gb31...@falafel.plessy.net
Re: Modifications of the changelog.
On 21.04.2012 09:35, Charles Plessy wrote: are there concrete problems caused by modifying previous changelog entries ? I do it from time to time, of course not when the diff has to be carefully inspected by others as it would be a distraction, and I have not found it causing breakages. The whole point of a changelog is a time dependent frozen point of view at your package. Once you released a version of a package, you should consider it untouchable as it would confuse people _a lot_ if you force them to read a full backlog of changes every time they upgrade because you /could/ have modified more than the latest entry. Generally speaking it may be ok-ish in important cases to change previous entry if you restrict yourself to spelling fixes and formating changes, but it is completely unacceptable [to me, at least] to reformulate entries, add entries, remove entries and such. Of course that's nothing which should be advocated on a mailing lists where the purpose of it is to assist people to make proper, well made and clean packages. -- with kind regards, Arno Töll IRC: daemonkeeper on Freenode/OFTC GnuPG Key-ID: 0x9D80F36D signature.asc Description: OpenPGP digital signature
Re: Modifications of the changelog.
Charles Plessy ple...@debian.org writes: are there concrete problems caused by modifying previous changelog entries ? Doing that breaks the entirely reasonable expectation: that a changelog only ever accumulates entries for the latest release, and nothing in earlier releases has changed since the last time the recipient read them. -- \ “Everyone is entitled to their own opinions, but they are not | `\entitled to their own facts.” —US Senator Pat Moynihan | _o__) | Ben Finney -- To UNSUBSCRIBE, email to debian-mentors-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/878vhocxos@benfinney.id.au
Re: Modifications of the changelog.
Le Sun, Apr 22, 2012 at 12:22:43PM +1000, Ben Finney a écrit : Charles Plessy ple...@debian.org writes: are there concrete problems caused by modifying previous changelog entries ? Doing that breaks the entirely reasonable expectation: that a changelog only ever accumulates entries for the latest release, and nothing in earlier releases has changed since the last time the recipient read them. Hi Ben, What is that expectation for ? I find it dogmatic written like this. If it breaks software, especially in Debian's infrastructure, that would be a key reason for not changing any byte. Otherwise, while there is probably better things to do in life than spellchecking a changelog, I admit that once I went through the first entry, I sometimes correct the ones below. I also remove trailing spaces that distract my eyes when colored in purple by my editor, and for the packages in Git, I sometimes added the first seven numbers of the commit hash to past entries. I also have added missing hashes so that when browsing the changelog on packages.d.o, one can have a nice hyperlink to bug reports, etc. I am not advocating that other people should do this, but I think that, especially on debian-mentors, strong statements about what everybody must not do should come with explanations about the reason, if possible argumented with concrete examples of the problems caused. Have a nice Sunday, -- Charles Plessy Tsurumi, Kanagawa, Japan -- To UNSUBSCRIBE, email to debian-mentors-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/20120422023931.ge19...@falafel.plessy.net
Re: Modifications of the changelog.
Ben Finney ben+deb...@benfinney.id.au writes: Charles Plessy ple...@debian.org writes: are there concrete problems caused by modifying previous changelog entries ? Doing that breaks the entirely reasonable expectation: that a changelog only ever accumulates entries for the latest release, and nothing in earlier releases has changed since the last time the recipient read them. I think the absolute prohibition takes things a bit too far. The changelog is documentation, and therefore can have bugs, just like any other documentation. If there is a bug, such as a missing entry for a change that was made in an earlier version, I fix it like any other bug: correct the changelog for that version, and add a note in the changelog for the most recent version that I fixed the documentation bug. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-mentors-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/87zka4v4vx@windlord.stanford.edu
