Re: [flame] NEWS file is useless
On 26 Nov 2009, at 22:15, Riccardo Mottola wrote: Not only in a ChangeLog I can write more than in a commit and I can group files and comment on sigle pieces of them, but it is an easy file I can check. Are you using a different svn to me? When I do a commit, it pops up $EDITOR (vim in my case, but apparently some people use the other one) and I can type as much as I want into it. I frequently put a couple of paragraphs into commit logs. Also, one interesting point: can I correct a svn commit message? Yes. It happens that I write wrong information or that I find a better way to explain it. With the ChangeLog it is easy... I commit a new improved version. What would you do with svn? svn propedit. Commit messages are in svn properties and can be edited just like any other properties. You can edit the commit message and it remains associated with the revision, so, for example people who use viewvc to browse the source code can jump to the commit log. If something has recently changed in NSOutlineView, for example, then I go here: http://svn.gna.org/viewcvs/gnustep/libs/gui/trunk/Source/NSOutlineView.m?rev=29065&dir_pagestart=150&view=log I get the commit message for each change and can see the diff side by side. If the person who made the change put the message in the ChangeLog instead, then I have to search in a separate file as well for each change that touched the file. In no possible way is that easier. Also, A ChangeLog is easy to search. When something breaks I grep in the changelog. Old habits. Why is: cat ChangeLog | grep easier than: svn log | grep Especially as the svn log line can be filtered to find the changes on a specific file just by specifying the file on the command line. David -- Sent from my Cray X1 ___ Gnustep-dev mailing list Gnustep-dev@gnu.org http://lists.gnu.org/mailman/listinfo/gnustep-dev
Re: [flame] NEWS file is useless
Hi, By the way, presumably we'd still include the author of the change in the subversion commit message ? Ie, we write a full ChangeLog entry including the author at the beginning ? The reason is that when we receive patches, the committer is often *not* the author of the patch, only the reviewer. With ChangeLog entries you can see who is the author of the patch, regardless of who did the actual commit. (and occasionally, some changes simply have two or more authors - again in ChangeLogs you just list multiple authors, while subversion logs can only record the committer) Thumbs up, I missed this point. But I too, when I commit a fix, cite the original author. Riccardo ___ Gnustep-dev mailing list Gnustep-dev@gnu.org http://lists.gnu.org/mailman/listinfo/gnustep-dev
Re: [flame] NEWS file is useless
On Thu, Nov 26, 2009 at 10:15 PM, Riccardo Mottola wrote: > David Chisnall wrote: >> >> On 25 Nov 2009, at 22:39, Richard Frith-Macdonald wrote: >> >>> There are actually three levels of change information ... >>> NEWS ... just the headlines >>> ReleaseNotes ... some more detail >>> ChangeLog ... everything >>> >>> Maybe you are right and we shouldn't bother with NEWS? I'd be interested >>> to know what others think. >> >> I'd be in favour of ditching NEWS and ChangeLog. >> >> ChangeLog has less information, in a less useful format, than the svn logs >> and is a hold-over from CVS not storing repository-wide change information >> sensibly. With svn log, you can get a log of change messages at any >> granularity that you like. If anyone actually cares about ChangeLog then >> they can do 'svn log > ChangeLog' on their local machine. Stuff in the svn >> log can be processed easily, and is easier for people to check than the >> ChangeLog, for example: > > Well, I disagree. > The utility of NEWS is questionable, but ChangeLog should be preserved. Not > only in a ChangeLog I can write more than in a commit and I can group files > and comment on sigle pieces of them, but it is an easy file I can check. > Also, ChangeLog gets released, so it is available in the end-suer release > tarball. I think we should keep the ChangeLog file, but I really don't see the point in NOT generating it automatically. Nothing prevent you to write more detailed commits logs, and it really feels like duplication to me (and you can always forget to modify the ChangeLog...). > ReleaseNotes may contain comments about incompatibilities, deprecations of > methods, upgrade procedures... > NEWS is perhaps more geared towards notable end-user readable things like > new features, big fixes. It is perhaps more useful for an Application than > the library. > > Riccardo > > > ___ > Gnustep-dev mailing list > Gnustep-dev@gnu.org > http://lists.gnu.org/mailman/listinfo/gnustep-dev > -- Nicolas Roard "I love deadlines. I like the whooshing sound they make as they fly by." -- Douglas Adams ___ Gnustep-dev mailing list Gnustep-dev@gnu.org http://lists.gnu.org/mailman/listinfo/gnustep-dev
Re: [flame] NEWS file is useless
Hi, I agree with Nicola here ... it's very, very far from being a waste of space ... people do need to be able to see the changes made to the code. So your suggestion of having a script make a ChangeLog automatically from the svn logs makes a *lot* of sense. WasteOfSpace? I think that is the last of our problems. Also, one interesting point: can I correct a svn commit message? It happens that I write wrong information or that I find a better way to explain it. With the ChangeLog it is easy... I commit a new improved version. What would you do with svn? Also, A ChangeLog is easy to search. When something breaks I grep in the changelog. Old habits. Riccardo ___ Gnustep-dev mailing list Gnustep-dev@gnu.org http://lists.gnu.org/mailman/listinfo/gnustep-dev
Re: [flame] NEWS file is useless
David Chisnall wrote: On 25 Nov 2009, at 22:39, Richard Frith-Macdonald wrote: There are actually three levels of change information ... NEWS ... just the headlines ReleaseNotes ... some more detail ChangeLog ... everything Maybe you are right and we shouldn't bother with NEWS? I'd be interested to know what others think. I'd be in favour of ditching NEWS and ChangeLog. ChangeLog has less information, in a less useful format, than the svn logs and is a hold-over from CVS not storing repository-wide change information sensibly. With svn log, you can get a log of change messages at any granularity that you like. If anyone actually cares about ChangeLog then they can do 'svn log > ChangeLog' on their local machine. Stuff in the svn log can be processed easily, and is easier for people to check than the ChangeLog, for example: Well, I disagree. The utility of NEWS is questionable, but ChangeLog should be preserved. Not only in a ChangeLog I can write more than in a commit and I can group files and comment on sigle pieces of them, but it is an easy file I can check. Also, ChangeLog gets released, so it is available in the end-suer release tarball. ReleaseNotes may contain comments about incompatibilities, deprecations of methods, upgrade procedures... NEWS is perhaps more geared towards notable end-user readable things like new features, big fixes. It is perhaps more useful for an Application than the library. Riccardo ___ Gnustep-dev mailing list Gnustep-dev@gnu.org http://lists.gnu.org/mailman/listinfo/gnustep-dev
Re: [flame] NEWS file is useless
On Thu, Nov 26, 2009, Nicola Pero wrote: > I also occasionally work on gnustep-make offline, and the subversion > logs are not available offline, while ChangeLogs are. Dare I say it, but the obvious answer to that is a DVCS, of which hg and git spring to mind. On Thu, Nov 26, 2009 at 11:08:01AM +, Nicola Pero wrote: > By the way, presumably we'd still include the author of the change in > the subversion commit message ? I'm not sure about the hg metadata (not having used it much yet), but certainly in git the commits inherently save author and commitor as seperate fields. But I guess the multiple author case you mention would snooker it. > I'm personally not too convinced. I guess it must be because I don't > use any tools based on subversion logs so I don't see a particular benefit. For personal stuff, I've been playing with git recently, which I've found useful for a program I've been testing/writing on both OSX & Linux. I _have_ found the ability to view commit logs (having produced suitably verbose commit messages) across arbitrary periods to be useful. (and the lack of such verbose commit logs at work has been a personal gripe of mine - but then the vcs system in use sucks). /phx ___ Gnustep-dev mailing list Gnustep-dev@gnu.org http://lists.gnu.org/mailman/listinfo/gnustep-dev
Re: [flame] NEWS file is useless
It's not a strict requirement. On Wednesday, November 25, 2009, wrote: > > > > I still haven't seen a convincing argument for it. Any of the information > that people write in the ChangeLog file they could also write in the commit > log. It is impossible to make a commit without writing a log message, it is > easy to make a commit without editing the ChangeLog (you could add a > pre-commit hook that prevented this, but no one has done so). > > David > > > I strongly agree. > > The main reason why I didn't commit the GNUstep Gnome Theme > into svn is because maintaining ChangLog would bother me too much. > > Hans > -- Gregory Casamento Open Logic Corporation, Principal Consultant ## GNUstep Chief Maintainer yahoo/skype: greg_casamento, aol: gjcasa (240)274-9630 (Cell), (301)362-9640 (Home) ___ Gnustep-dev mailing list Gnustep-dev@gnu.org http://lists.gnu.org/mailman/listinfo/gnustep-dev
Re: [flame] NEWS file is useless
On 26 Nov 2009, at 11:08, Nicola Pero wrote: By the way, presumably we'd still include the author of the change in the subversion commit message ? Ie, we write a full ChangeLog entry including the author at the beginning ? Yes. If you look in the LLVM svn log, for example, you will see a few with 'Patch by David Chisnall!' at the end of a number of commit messages from before I got commit access. You'll see the same (e.g. 'Patch by Niels Grewe') at the end of a number of Étoilé commits. This makes it very easy to find commits by a third party. By the way, svn commit logs are stored in properties. It's possible to edit them after the commit by setting the log property on the commit. If someone can parse the ChangeLog file, the old ChangeLog entries can be imported into svn logs easily. David -- Sent from my Cray X1 ___ Gnustep-dev mailing list Gnustep-dev@gnu.org http://lists.gnu.org/mailman/listinfo/gnustep-dev
Re: [flame] NEWS file is useless
On 26 Nov 2009, at 11:08, Nicola Pero wrote: >> So I guess the solution to that would be instead to require ChangeLog >> entries to be committed to svn log. > > By the way, presumably we'd still include the author of the change in the > subversion commit message ? > Ie, we write a full ChangeLog entry including the author at the beginning ? > > The reason is that when we receive patches, the committer is often *not* the > author of the patch, only the reviewer. > With ChangeLog entries you can see who is the author of the patch, regardless > of who did the actual commit. > (and occasionally, some changes simply have two or more authors - again in > ChangeLogs you just list multiple > authors, while subversion logs can only record the committer) > > I'm personally not too convinced. I guess it must be because I don't use any > tools based on subversion logs > so I don't see a particular benefit. Anyway, we can change things. I'd ideally like to see the ChangeLog file maintained by the svn system (ie when you check in any change in svn, it updates the ChangeLog and stores the updated version in svn). I seem to recall writing a script to do that on our old CVS system at Brainstorm. Failing that, we could just have a system which regenerates the ChangeLog on demand (eg. 'make ChangeLog') and when making a snapshot/release. Let's say that policy is that people should write full, detailed entries (like ChangeLog entries) for the svn logs. Then it ought to be possible to take the output of 'svn -v log' and produce a reasonable ChangeLog entry listing the modification date, the files modified, and the log entry. This would mean that the log entry had to apply to all files in the transaction, but I'm not sure that's such a bad thing. So instead of 2007-12-08 Richard Frith-Macdonald * GNUmakefile: bump subminor version for release * GSThroughput.m: ([-description]) output information for periods from last cycle as well as current cycle. You might get 2007-12-08 Richard Frith-Macdonald * GNUmakefile: * GSThroughput.m: Bump subminor version for release ([-description]) output information for periods from last cycle as well as current cycle. In the first case I wrote the entire entry as a ChangeLog entry. In the second case I would have written Bump subminor version for release ([-description]) output information for periods from last cycle as well as current cycle. as an svn log entry, However, I suppose a better log entry might have been: Bump subminor version for release in make file. ([GSThroughput-description]) output information for periods from last cycle as well as current cycle. Possibly this was a poor example because the two changes are not really related and don't need to be in a single svn transaction. I think, generally, when you commit a multi-file transaction, the changes normally are related, and having a single long entry describing the changes actually makes good sense. ___ Gnustep-dev mailing list Gnustep-dev@gnu.org http://lists.gnu.org/mailman/listinfo/gnustep-dev
Re: [flame] NEWS file is useless
On 26 Nov 2009, at 11:03, Nicola Pero wrote: > >> It would be good to consider exactly how much (if any) information we want >> to present in NEWS/ReleaseNotes ... my preference would be for minimal >> information there, and a pointer to a generated ChangeLog for details. >> This would require a policy that svn log entries should be suitable for app >> developers (users of the libraries), not just for people writing the >> libraries themselves > > > I agree that it would be good to have ChangeLog entries that are well written > and readable by people who are not working on the software themselves :-) > > I still think NEWS (and/or Release Notes) need to be written separately as an > additional task. We shouldn't be lazy with documentation ;-) Yes, I think we need somethings, but as I said I'd like is 'minimal' ... an overview rather than the sort of detail in the ChangeLog. > I guess it depends on the piece of software, but for example our core > libraries have a large user base, and it's worth > spending some time writing clearly readable NEWS/ReleaseNotes. If you don't > write them, you'll spend 10x the time answering > questions via email about changes to the library anyway, so it even saves > time in practice to spend time documenting > changes! ;-) Well, ideally I'd like that sort of detail to be in the ChangeLog (and as I'm advocating generating the ChangeLog from the svn entries, that means I'd like information in the svn entries going into helpful detail). > Finally, NEWS/ReleaseNotes are important for marketing - any time we > implement something good, we should tell the world! > NEWS/ReleaseNote tend to for the basis for public announcements or tend to > end up on websites etc. so we should work on them. Sounds right to me ... the place for a publicity overview rather than technical detail. I think that should be kept short and easily quotable. > >> Lastly ... I'm not even sure that the historical policies on ChangeLog etc >> are written down anywhere > > They are part of the GNU Coding Standards, > http://www.gnu.org/prep/standards/html_node/Change-Logs.html Thanks. ___ Gnustep-dev mailing list Gnustep-dev@gnu.org http://lists.gnu.org/mailman/listinfo/gnustep-dev
Re: [flame] NEWS file is useless
So I guess the solution to that would be instead to require ChangeLog entries to be committed to svn log. By the way, presumably we'd still include the author of the change in the subversion commit message ? Ie, we write a full ChangeLog entry including the author at the beginning ? The reason is that when we receive patches, the committer is often *not* the author of the patch, only the reviewer. With ChangeLog entries you can see who is the author of the patch, regardless of who did the actual commit. (and occasionally, some changes simply have two or more authors - again in ChangeLogs you just list multiple authors, while subversion logs can only record the committer) I'm personally not too convinced. I guess it must be because I don't use any tools based on subversion logs so I don't see a particular benefit. Anyway, we can change things. Thanks ___ Gnustep-dev mailing list Gnustep-dev@gnu.org http://lists.gnu.org/mailman/listinfo/gnustep-dev
Re: [flame] NEWS file is useless
It would be good to consider exactly how much (if any) information we want to present in NEWS/ReleaseNotes ... my preference would be for minimal information there, and a pointer to a generated ChangeLog for details. This would require a policy that svn log entries should be suitable for app developers (users of the libraries), not just for people writing the libraries themselves I agree that it would be good to have ChangeLog entries that are well written and readable by people who are not working on the software themselves :-) I still think NEWS (and/or Release Notes) need to be written separately as an additional task. We shouldn't be lazy with documentation ;-) I guess it depends on the piece of software, but for example our core libraries have a large user base, and it's worth spending some time writing clearly readable NEWS/ReleaseNotes. If you don't write them, you'll spend 10x the time answering questions via email about changes to the library anyway, so it even saves time in practice to spend time documenting changes! ;-) Finally, NEWS/ReleaseNotes are important for marketing - any time we implement something good, we should tell the world! NEWS/ReleaseNote tend to for the basis for public announcements or tend to end up on websites etc. so we should work on them. Lastly ... I'm not even sure that the historical policies on ChangeLog etc are written down anywhere They are part of the GNU Coding Standards, http://www.gnu.org/prep/standards/html_node/Change-Logs.html Thanks ___ Gnustep-dev mailing list Gnustep-dev@gnu.org http://lists.gnu.org/mailman/listinfo/gnustep-dev
Re: [flame] NEWS file is useless
ChangeLog has less information, in a less useful format, than the svn logs and is a hold-over from CVS not storing repository-wide change information sensibly. With svn log, you can get a log of change messages at any granularity that you like. I agree there is an overlap, but there are also some differences. ;-) Subversion records a single log message for an entire transaction, which might contain changes to a number of files. A ChangeLog entry is supposed to contain a separate log message for every file that was changed. You realise that svn lets you commit changes to different files separately, right? If you have independent out-of-tree changes, commit them separately (see r29053 to r29055; three commits, all created together but committed separately to provide different log messages). I agree with your later point that you could simply write a ChangeLog entry in the subversion log - that way you still use subversion transactions properly, but document the changes to all files. :-) I don't think committing files separately makes sense instead - because you lose all the benefits of subversion transactions. If you get interrupted or lose network access between committing the separate files, the repository will be left in a broken state. That is bad. Also, I do like having in the logs the information that the changes are part of the same transaction. You do a single diff and see all the related changes to the different files, which is great. :-) So I guess the solution to that would be instead to require ChangeLog entries to be committed to svn log. Finally, the obvious advantage of a ChangeLog is that every source code distribution/tarball will include it. Subversion logs are only available if you use subversion. Subversion is available to anyone with access to the svn repository. Yes, but in practice it is a pain for people who are not following the project. When I install software from third-parties, I hate when they don't include a properly detailed ChangeLog - eg, if I need to check if a certain bug in a certain file was fixed between version 1.7.4 and 1.7.5, I just want to download the 1.7.5 tarball and check the ChangeLog. I don't want to have to set up whatever versioning system they use just to check a single file - it takes time because every project uses a different one, etc. I also occasionally work on gnustep-make offline, and the subversion logs are not available offline, while ChangeLogs are. People can track it by subscribing to the RSS feed from cia.vc, they can see an individual committer's changes by looking at the timeline on Ohloh.net. Sure, that is certainly good. If someone wants to do 'svn log > ChangeLog' when creating the tarballs, they can; just add it to the script you use to generate the tarball. Given that most tarball downloads are likely to be from people who just want to build the code, however, it seems like a waste of space. It's definitely not a waste of space. ;-) But if we were to agree that people would write ChangeLog entries in the subversion logs, then we could generate the ChangeLog from the subversion logs before release. Even if in practice that can be hard, since all the interesting information for existing projects is currently in ChangeLogs, so we'd need to prepend to these ChangeLogs the latest ChangeLog entries from the subversion logs, but the system would need to be able to figure out which logs to prepend and which to ignore. Maybe a commit hook that copies the subversion log to the ChangeLog file makes more sense then, so the ChangeLog would automatically be updated whenever you commit. If we want to go through this route, that would be ideal I guess. So maybe we could adopt a different approach depending on the project. I certainly think ChangeLogs are very good for the core libraries. I still haven't seen a convincing argument for it. Any of the information that people write in the ChangeLog file they could also write in the commit log. It is impossible to make a commit without writing a log message, it is easy to make a commit without editing the ChangeLog (you could add a pre-commit hook that prevented this, but no one has done so). You're right that writing a subversion commit message is enforced, while writing a ChangeLog entry is not. But on the other hand, ChangeLog entries must be in a certain format that require you to write a description of each change to each file, while subversion log messages enforce no format and people tend to write extremely short, unexpressive messages such as "fixed bug" or "improved performance" when they maybe have changed hundreds of lines in lots of different files. When you're later trying to debug some failures caused by an old change, you need some information on what they were trying to achieve, or why things were changed - a more serious and detailed des
Re: [flame] NEWS file is useless
On 26 Nov 2009, at 01:10, David Chisnall wrote: > On 26 Nov 2009, at 00:50, Nicola Pero wrote: > >>> I'd be in favour of ditching NEWS and ChangeLog. >>> >>> ChangeLog has less information, in a less useful format, than the svn logs >>> and is a hold-over from CVS not storing repository-wide change information >>> sensibly. With svn log, you can get a log of change messages at any >>> granularity that you like. >> >> I agree there is an overlap, but there are also some differences. ;-) >> >> Subversion records a single log message for an entire transaction, which >> might contain changes to a number of files. >> A ChangeLog entry is supposed to contain a separate log message for every >> file that was changed. > > You realise that svn lets you commit changes to different files separately, > right? If you have independent out-of-tree changes, commit them separately > (see r29053 to r29055; three commits, all created together but committed > separately to provide different log messages). Agreed ... it's sometimes a bit inconvenient to use svn that way (and leaves a small window in which people can check out inconsistent code), but not a real problem. >> Finally, the obvious advantage of a ChangeLog is that every source code >> distribution/tarball will include it. Subversion logs are only >> available if you use subversion. > > Subversion is available to anyone with access to the svn repository. People > can track it by subscribing to the RSS feed from cia.vc, they can see an > individual committer's changes by looking at the timeline on Ohloh.net. The > information is available in a form that is easy for tools to process. > If someone wants to do 'svn log > ChangeLog' when creating the tarballs, > they can; just add it to the script you use to generate the tarball. Given > that most tarball downloads are likely to be from people who just want to > build the code, however, it seems like a waste of space. I agree with Nicola here ... it's very, very far from being a waste of space ... people do need to be able to see the changes made to the code. So your suggestion of having a script make a ChangeLog automatically from the svn logs makes a *lot* of sense. >> I still see your point - particularly for new software, written from scratch >> by a single person and not yet really released, it is faster >> to just code it all and write short subversion logs for each commit - it >> sounds superfluous to also write ChangeLog entries. But >> once the software is quite finished and stable, is widely used and released, >> and we're polishing it while being extremely careful >> not to break things, then a more careful approach where every change is >> documented in great detail (and even redundantly) looks >> good to me. ;-) > > Writing a ChangeLog entry does not make you more careful, it just makes you > either write duplicate information, or split the useful information between > the ChangeLog file and the svn log. Unfortunately true ... I must confess that, since the ChangeLog is the official repository of this information, I tend to write more informative stuff there than in the svn logs ... so there's duplication, but it's lossy/imperfect because it's just easier that way, especially when working in environments without cut-and-paste (yes, I still do that quite a bit) and when I suddenly get interrupted. >> So maybe we could adopt a different approach depending on the project. I >> certainly think ChangeLogs are very good for the core >> libraries. > > I still haven't seen a convincing argument for it. Any of the information > that people write in the ChangeLog file they could also write in the commit > log. It is impossible to make a commit without writing a log message, it is > easy to make a commit without editing the ChangeLog (you could add a > pre-commit hook that prevented this, but no one has done so). I really don't like the current situation where we have a split between historical/official practices of using ChangeLog and newcomers using svn log entries. I think my own behavior has been 'corrupted' by the widespread use of svn logs ... I suspect the quality of my ChangeLog entries has dropped, not for any good reason but just because of a slight mental conflict at the point when I'm committing changes. While ChangeLog has its advantages, the fact that we are using svn, which has it's own logs means that the svn logs really have to 'win' if you want to avoid the duplication. I would like to support dropping ChangeLog. For this to work we need two things: 1. technical changes to address any disadvantages of svn logs. 2. official policy change For (1) I think the only real issue is that of generating a ChangeLog file from the svn logs for inclusion in any distributions. I think Nicola might lead on that, as we create releases and snapshots using special targets in gnustep-make, and those targets would need to be updated to genera
