* Writing changelog entries @ 2005-01-04 20:31 Florian Weimer 2005-01-04 23:51 ` Randy Brukardt 2005-01-05 0:28 ` Stephen Leake 0 siblings, 2 replies; 12+ messages in thread From: Florian Weimer @ 2005-01-04 20:31 UTC (permalink / raw) How are you writing your changelog entries? There are a few Ada-specific questions. Shall I include the package name, or is the file name enough? How does one deal with homonyms? Here's an example, but I'm not completely satisfied with it. Then again, I don't use changelogs much because I wrote most of the code pretty recent and it's still a small project (by Ada's standard, not necessarily by mine). ---------------------------------------------------------------------- r762: fw | 2005-01-04 21:26:27 +0100 * lib/core/enyo-io.ads, lib/core/enyo-io.adb (Put): New procedure which copies data from one buffer to another. * lib/core/enyo-io-file_queues.ads, lib/core/enyo-io-file_queues.adb (Write): Rename to Put. (Put): New procedure which copies the contents of a buffer. * test/tests-io-channels.adb, test/tests-io.adb: Adjust old Put calls. * test/tests-io-file_queues.adb: Adjust old Write calls. New test case for Put of a buffer. ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Writing changelog entries 2005-01-04 20:31 Writing changelog entries Florian Weimer @ 2005-01-04 23:51 ` Randy Brukardt 2005-01-05 0:28 ` Stephen Leake 1 sibling, 0 replies; 12+ messages in thread From: Randy Brukardt @ 2005-01-04 23:51 UTC (permalink / raw) "Florian Weimer" <fw@deneb.enyo.de> wrote in message news:87y8f96imj.fsf@deneb.enyo.de... > How are you writing your changelog entries? Change log entries for what? The answers vary depending on the purpose. I generally put brief notes into the source code ("Edit History") and the VCS, and that's it. For user-level lists of feature changes, I make general descriptions of the change. So I guess I rarely use package names or any of that sort of level stuff in my comments. If I need it again, I can get it from the VCS diffs and change lists -- the notes usually are for that purpose -- and using a tool is always preferable to anything created by hand. Of course, if there is anything "interesting", I put lots of comments in at the locus of the change - so I'll see them the next time I'm working in that area. Randy. ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Writing changelog entries 2005-01-04 20:31 Writing changelog entries Florian Weimer 2005-01-04 23:51 ` Randy Brukardt @ 2005-01-05 0:28 ` Stephen Leake 2005-01-05 0:47 ` Florian Weimer 2005-01-05 12:31 ` Pascal Obry 1 sibling, 2 replies; 12+ messages in thread From: Stephen Leake @ 2005-01-05 0:28 UTC (permalink / raw) To: comp.lang.ada Florian Weimer <fw@deneb.enyo.de> writes: > How are you writing your changelog entries? This is probably highly project specific, but I'll give you what I do. I just use Emacs and CVS, and then when I do a release, I use cvs2cl.pl (http://www.red-bean.com/cvs2cl/) to generate a changelog. -- -- Stephe ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Writing changelog entries 2005-01-05 0:28 ` Stephen Leake @ 2005-01-05 0:47 ` Florian Weimer 2005-01-05 2:02 ` Stephen Leake 2005-01-06 20:19 ` Randy Brukardt 2005-01-05 12:31 ` Pascal Obry 1 sibling, 2 replies; 12+ messages in thread From: Florian Weimer @ 2005-01-05 0:47 UTC (permalink / raw) * Stephen Leake: > Florian Weimer <fw@deneb.enyo.de> writes: > >> How are you writing your changelog entries? > > This is probably highly project specific, but I'll give you what I do. > > I just use Emacs and CVS, and then when I do a release, I use > cvs2cl.pl (http://www.red-bean.com/cvs2cl/) to generate a changelog. Generating the changelog is not the problem. It's the format of the entries in it. Many projects have explicit guidelines which ensure that you can grep the changelog and find the change which affected a particular entity. However, these guidelines are C-specific and do not take homographs into account (and neither nested subprograms, and so on). ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Writing changelog entries 2005-01-05 0:47 ` Florian Weimer @ 2005-01-05 2:02 ` Stephen Leake 2005-01-06 20:19 ` Randy Brukardt 1 sibling, 0 replies; 12+ messages in thread From: Stephen Leake @ 2005-01-05 2:02 UTC (permalink / raw) To: comp.lang.ada Florian Weimer <fw@deneb.enyo.de> writes: > Many projects have explicit guidelines which ensure that you can > grep the changelog and find the change which affected a particular > entity. I never use a changelog for that. In fact, I never do that. But I guess I haven't been involved in a large project where that would be necessary; all my projects are small enough that I know what's going on anyway, by keeping up with daily CVS updates. > However, these guidelines are C-specific and do not take homographs > into account (and neither nested subprograms, and so on). Right. Hmm. You want a CM tool that can answer the query: what changes affected <name>. I don't know of any CM tools that do that directly; it would require the CM tool to understand the language. In Ada, every name can be spelled uniquely; for overloaded functions you need to include the parameter/result profile, etc. So you could have a style guide that says "when checking in changes, include the _unique_ name of every item affected". Yuck; that would be a huge burden on the programmers. You could write an ASIS tool to generate that name list by comparing the two versions of the file; you can have CVS run that tool and append the result to the checkin comment. Hmm. Getting both versions into one ASIS context would be tricky; you'd need a top level namespace for each version. Whether that's worth doing depends on how often you do this query, and how important it is. Hmm. You could have the CM tool generate the diffs for each change, and then grep that for <name>. That might be efficient, but it doesn't address the homograph issue. -- -- Stephe ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Writing changelog entries 2005-01-05 0:47 ` Florian Weimer 2005-01-05 2:02 ` Stephen Leake @ 2005-01-06 20:19 ` Randy Brukardt 2005-01-07 23:32 ` Brian May 1 sibling, 1 reply; 12+ messages in thread From: Randy Brukardt @ 2005-01-06 20:19 UTC (permalink / raw) "Florian Weimer" <fw@deneb.enyo.de> wrote in message news:87wtus3do0.fsf@deneb.enyo.de... > Generating the changelog is not the problem. It's the format of the > entries in it. Many projects have explicit guidelines which ensure > that you can grep the changelog and find the change which affected a > particular entity. However, these guidelines are C-specific and do > not take homographs into account (and neither nested subprograms, and > so on). My personal opinion is that that is not worth it. Changes should have been at least minimally tested before being checked it, and if they cause a regression test to fail, they should be fixed immediately while the programmer still remembers what he did. (They then won't need to work back through the system.) That leaves the rare cases where a problem shows up much later. In those cases, it's usually necessary to debug the entire thing again anyway. So, leaving comments in the place where the code is the most valuable, because it's where you're going to be looking anyway. If it takes two extra minutes (probably conservative) to create structured changelogs, you'd have to save more than 4 hours of development time to come out ahead on the 1 out of 100 (probably pessimistic) changes that you have go back and debug in the future. While that's possible, it seems unlikely. Just having the CM (with no changelog at all) seems to save most of the time; I do try to put the bug report number into the code and/or edit history (presuming it is formally tracked; we only do that for outside bug reports, because of the time investment), which helps find the change again if needed. Randy. ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Writing changelog entries 2005-01-06 20:19 ` Randy Brukardt @ 2005-01-07 23:32 ` Brian May 2005-01-08 2:12 ` Stephen Leake 2005-01-10 20:57 ` Randy Brukardt 0 siblings, 2 replies; 12+ messages in thread From: Brian May @ 2005-01-07 23:32 UTC (permalink / raw) >>>>> "Randy" == Randy Brukardt <randy@rrsoftware.com> writes: Randy> That leaves the rare cases where a problem shows up much Randy> later. In those cases, it's usually necessary to debug the Randy> entire thing again anyway. So, leaving comments in the Randy> place where the code is the most valuable, because it's Randy> where you're going to be looking anyway. Then you come to a line of code that is causing problems. You can't remember why the line was in its current form (probably a mistake, and you change it to what looks correct. Months later you observe a different problem. You change the same line of code back to the original value, because you can't remember why you changed it before, and it looked totally wrong before. Months later you observe the original problem again. After hours of debugging, you end up changing the same line of code back to the modified value, because you can't remember why you changed it before, and it looked totally wrong before. ...repeat... See a pattern here? Meanwhile, the real bug is not getting fixed. You should be documenting *why* changes are made so you don't have to reinvent the wheel every time you encounter the same problem again. Comments in the code only really describe what the code does (or more precisely: what it is meant to do), not why a change was made. Yes, you could document a complete history of why you made every change as comments in the source code, a changelog file would appear to be better suited for the purpose though. Also, a good changelog is required if you want to upgrade numerous systems, and want some idea of what is likely to break in the upgrade. Not to mention security related issues. A good changelog may help identify what versions of the software had a serious security bug for instance. -- Brian May <bam@snoopy.apana.org.au> ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Writing changelog entries 2005-01-07 23:32 ` Brian May @ 2005-01-08 2:12 ` Stephen Leake 2005-01-10 20:57 ` Randy Brukardt 1 sibling, 0 replies; 12+ messages in thread From: Stephen Leake @ 2005-01-08 2:12 UTC (permalink / raw) To: comp.lang.ada Brian May <bam@snoopy.apana.org.au> writes: > You should be documenting *why* changes are made so you don't have to > reinvent the wheel every time you encounter the same problem again. If you document why the code is the way it is, _and_ why it is not some other way that you considered, you can terminate the perpetual changes. Such documentation belongs in the code as comments if it is short enough, or in a separate design document, with a reference in the code. > Comments in the code only really describe what the code does (or > more precisely: what it is meant to do), not why a change was made. > Yes, you could document a complete history of why you made every > change as comments in the source code, a changelog file would appear > to be better suited for the purpose though. Change logs are not design documents. -- -- Stephe ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Writing changelog entries 2005-01-07 23:32 ` Brian May 2005-01-08 2:12 ` Stephen Leake @ 2005-01-10 20:57 ` Randy Brukardt 1 sibling, 0 replies; 12+ messages in thread From: Randy Brukardt @ 2005-01-10 20:57 UTC (permalink / raw) "Brian May" <bam@snoopy.apana.org.au> wrote in message news:sa48y74n7bq.fsf@snoopy.apana.org.au... > >>>>> "Randy" == Randy Brukardt <randy@rrsoftware.com> writes: > > Randy> That leaves the rare cases where a problem shows up much > Randy> later. In those cases, it's usually necessary to debug the > Randy> entire thing again anyway. So, leaving comments in the > Randy> place where the code is the most valuable, because it's > Randy> where you're going to be looking anyway. > > Then you come to a line of code that is causing problems. > > You can't remember why the line was in its current form (probably a > mistake, and you change it to what looks correct. The code should be commented as to why it is the way currently is. Of course, that isn't always done (when it appears obvious). But if a bug report causes a change, usually I'll include the bug report number and an explanation of why the code needs to be the way it is. > Months later you observe a different problem. You change the same line > of code back to the original value, because you can't remember why you > changed it before, and it looked totally wrong before. Well, unless I've lost the ability to read comments, that's not likely to be an issue. Moreover, I would be remiss if I don't use the bug report number to look up the associated regression test to insure that I didn't reintroduce a bug. > Months later you observe the original problem again. After hours of > debugging, you end up changing the same line of code back to the > modified value, because you can't remember why you changed it before, > and it looked totally wrong before. Couldn't happen: even if I didn't manually check for a regression, the regression tests (which are run very often - usually immediately after a change) would have caught the problem. For this to happen, I've have to have failed to comment the code *and* failed to create a regression test. I'd fire myself if I did that! > ...repeat... > > See a pattern here? Sure; some people neither create tests nor properly comment their code. What good would a changelog do? It's widely separated from the code in question; I don't want to have to look in a half dozen places to understand some code! And if people aren't putting in useful comments or creating tests, why would they write a useful changelog?? (Certainly, if I didn't do the first two because I was in too much of hurry, the third will be even more useless...) > Meanwhile, the real bug is not getting fixed. > > You should be documenting *why* changes are made so you don't have to > reinvent the wheel every time you encounter the same problem again. Absolutely. At the place of the bug, in the code where you can't help but see it the next time your debugging path leads you there. > Comments in the code only really describe what the code does (or more > precisely: what it is meant to do), not why a change was made. Those would be pretty useless comments. The only comments that *are* useful are those that explain *why* code is the way it is. The other questions (what, where) usually can be answered by reading the code itself. > Yes, you could document a complete history of why you made every change as > comments in the source code, a changelog file would appear to be > better suited for the purpose though. I don't see why; it's widely separated from the code in question. There is no sane way to associate the descriptions with the code -- and that's what you need to understand the code and avoid reintroducing problems. I don't believe in separate design documents (other than for "big picture" sorts of descriptions), either. > Also, a good changelog is required if you want to upgrade numerous > systems, and want some idea of what is likely to break in the upgrade. We always tried to keep the systems maintained in parallel. Traditional source code control systems do a lousy job of this, and we wrote our own tools to manage the files (most of them are shared between the versions, only a few need manual upgrades). But I realize that won't work everywhere. > Not to mention security related issues. A good changelog may help > identify what versions of the software had a serious security bug for > instance. That seems like a job for a bug tracking database. We've never computerized that (I still use the paper-based system we worked out in the 80s), but it would be easy enough to do. I don't want to claim that the changelog has no use whatsoever, but I don't think there is much point to getting fancy with it. There are better places for virtually all of the information that could be in it; you just need enough to insure that you can find a particular change in the rare case that you need to see how you got to the current code. Randy. ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Writing changelog entries 2005-01-05 0:28 ` Stephen Leake 2005-01-05 0:47 ` Florian Weimer @ 2005-01-05 12:31 ` Pascal Obry 2005-01-05 23:29 ` Stephen Leake 1 sibling, 1 reply; 12+ messages in thread From: Pascal Obry @ 2005-01-05 12:31 UTC (permalink / raw) Stephen Leake <stephen_leake@acm.org> writes: > I just use Emacs and CVS, and then when I do a release, I use > cvs2cl.pl (http://www.red-bean.com/cvs2cl/) to generate a changelog. I do the opposite. Using PCL-CVS (as you :) I use the shift-A key on the modified file in the PCL-CVS *cvs* buffer. This open the right ChangeLog file (in the current directory or in the parent one) and I edit the revision history there. I do that for all files to commit. Then when ready I do a shift-C on each files. The last step is to commit the ChangeLog file itself. Pascal. -- --|------------------------------------------------------ --| Pascal Obry Team-Ada Member --| 45, rue Gabriel Peri - 78114 Magny Les Hameaux FRANCE --|------------------------------------------------------ --| http://www.obry.org --| "The best way to travel is by means of imagination" --| --| gpg --keyserver wwwkeys.pgp.net --recv-key C1082595 ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Writing changelog entries 2005-01-05 12:31 ` Pascal Obry @ 2005-01-05 23:29 ` Stephen Leake 2005-01-06 17:51 ` Pascal Obry 0 siblings, 1 reply; 12+ messages in thread From: Stephen Leake @ 2005-01-05 23:29 UTC (permalink / raw) To: comp.lang.ada Pascal Obry <pascal@obry.org> writes: > Stephen Leake <stephen_leake@acm.org> writes: > > > I just use Emacs and CVS, and then when I do a release, I use > > cvs2cl.pl (http://www.red-bean.com/cvs2cl/) to generate a changelog. > > I do the opposite. Using PCL-CVS (as you :) I use the shift-A key on the > modified file in the PCL-CVS *cvs* buffer. This open the right ChangeLog file > (in the current directory or in the parent one) and I edit the revision > history there. I do that for all files to commit. Then when ready I do a > shift-C on each files. Does that read the Changelog file and use the comment for the commit? Or is the CVS commit comment left empty? -- -- Stephe ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: Writing changelog entries 2005-01-05 23:29 ` Stephen Leake @ 2005-01-06 17:51 ` Pascal Obry 0 siblings, 0 replies; 12+ messages in thread From: Pascal Obry @ 2005-01-06 17:51 UTC (permalink / raw) Stephen Leake <stephen_leake@acm.org> writes: > Does that read the Changelog file and use the comment for the commit? Yes that does all the work for you. You just need to do a ctrl-c/ctrl-c Magic :) Pascal. -- --|------------------------------------------------------ --| Pascal Obry Team-Ada Member --| 45, rue Gabriel Peri - 78114 Magny Les Hameaux FRANCE --|------------------------------------------------------ --| http://www.obry.org --| "The best way to travel is by means of imagination" --| --| gpg --keyserver wwwkeys.pgp.net --recv-key C1082595 ^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2005-01-10 20:57 UTC | newest] Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2005-01-04 20:31 Writing changelog entries Florian Weimer 2005-01-04 23:51 ` Randy Brukardt 2005-01-05 0:28 ` Stephen Leake 2005-01-05 0:47 ` Florian Weimer 2005-01-05 2:02 ` Stephen Leake 2005-01-06 20:19 ` Randy Brukardt 2005-01-07 23:32 ` Brian May 2005-01-08 2:12 ` Stephen Leake 2005-01-10 20:57 ` Randy Brukardt 2005-01-05 12:31 ` Pascal Obry 2005-01-05 23:29 ` Stephen Leake 2005-01-06 17:51 ` Pascal Obry
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox