Thread: Maintaining the list of release changes
Would it be too much to ask for that everytime a significant user-visible change is checked in, the release notes are updated right there as though they are documentation (which they are)? This immediately leads to three significant advantages: 1. Users can keep track of developement. Until after the start of beta, no user really had any idea what this new release was going to be about. Users that startedprojects before the release notes were in readable form were wasting their time, if they chose PostgreSQL at all. 2. Developers can keep track of development. The number of changes for 7.2 is really enough for five releases, but no one can be expected to keep track of that. Soin the future, when the list gets too long, we make a release. ;-) 3. The list accurately reflects the actual work. Having the list reconstructed by a single person from CVS logs months after the fact is just way too lossy. -- Peter Eisentraut peter_e@gmx.net
Peter Eisentraut <peter_e@gmx.net> writes:
> Would it be too much to ask for that everytime a significant
> user-visible change is checked in, the release notes are updated right
> there as though they are documentation (which they are)?
> Having the list reconstructed by a single person from CVS logs months
> after the fact is just way too lossy.
I agree completely, and was about to make a similar proposal. However,
I'm not entirely sure where "the release notes" actually are, nor which
is the master copy. Also, I'd prefer not to have to deal with SGML
markup for them.
What I'd suggest is that we keep a plaintext file somewhere near the
top of the CVS tree (in doc/ perhaps) that developers append
release-notes items to as the work is completed. At the end of each
development cycle, Bruce can prepare the "nice looking" notes from that
source and then reset the file to empty for the next cycle.
regards, tom lane
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> Sure, just stick stuff at the top of the HISTORY file and I can deal
> with it during release packaging. I will tell you that many one-line
> release items are made up of many commits and decisions so there is
> little likelyhood I can just cut/paste and avoid the CVS log grovel but
> it will help new folks.
Well, if you expect to have to grovel through the CVS logs anyway,
another possibility is to put the info into the CVS commit messages.
Perhaps we could agree on a convention that commits that include
release-note-worthy material should have something like
RELEASE NOTE: descriptive paragraph here
in the commit message. Keep basically the same process, but make it
easier for Bruce to spot the important material.
I think I prefer the file-of-notes idea, but this is a possibility worth
suggesting.
regards, tom lane
Bruce Momjian <pgman@candle.pha.pa.us> writes:
>> I think I prefer the file-of-notes idea, but this is a possibility worth
>> suggesting.
> We can do whatever people want. I was just afraid it would be too much
> work for people, and I am willing to continue doing it. Actually, if
> people want to help, looking over the final is 10x more valuable than
> having a separate file, at least for me.
Even if people do review the notes, who's to say they'll remember a
change they made months ago? I think it's important for developers to
prepare at least a rough-draft entry for the release notes at the time
the change is made. We can debate different ways to keep that info
available until the docs are prepared, but the real problem here is to
not rely on memory.
regards, tom lane
On Fri, Feb 08, 2002 at 04:03:39PM -0500, Tom Lane wrote: > Bruce Momjian <pgman@candle.pha.pa.us> writes: > >> I think I prefer the file-of-notes idea, but this is a possibility worth > >> suggesting. > > > We can do whatever people want. I was just afraid it would be too much > > work for people, and I am willing to continue doing it. Actually, if > > people want to help, looking over the final is 10x more valuable than > > having a separate file, at least for me. > > Even if people do review the notes, who's to say they'll remember a > change they made months ago? I think it's important for developers to > prepare at least a rough-draft entry for the release notes at the time > the change is made. We can debate different ways to keep that info > available until the docs are prepared, but the real problem here is to > not rely on memory. The _really_ critical piece for making this cumulative file work: _every_ user visible change needs to go into it, at the time it's commited to CVS. Be hardnosed, so external patches _must_ touch that file, or put it in the commit log. The problem with the commit log is that it puts the onus on the CVS commiter, not the patch maker. I'm partial to a combo - a 'USER VISIBLE CHANGES: <yes|no>' line in CVS commit logs (put it in the template, default to yes?) and every 'yes' submit _must_ patch the cumulative release file. Ross
"Ross J. Reedstrom" <reedstrm@rice.edu> writes:
> I'm partial to a combo - a 'USER VISIBLE CHANGES: <yes|no>' line in CVS
> commit logs (put it in the template, default to yes?) and every 'yes'
> submit _must_ patch the cumulative release file.
I find it hard to imagine a patch that doesn't create *some* kind of
user-visible change, at some level. The question here is whether it
rises to the level of needing an entry in the release notes. If we
wanted a commit-by-commit release history we'd just tell people to read
the CVS logs; in practice that's no help. The point of release notes is
to hit the high spots, and that requires a certain amount of judgment.
So I don't think a mechanical "you must provide this" rule will help
much. We should rely on the judgment of the committer to decide whether
a release note is warranted. What we want is a reasonably simple way
for the committer to provide a draft note, and a mechanism to ensure
that Bruce doesn't miss the note later.
In the case that started this thread, I had actually provided material
for a release note in the CVS commit entry, but Bruce had skipped over
it because he didn't think it important. The missing link was that
I didn't have a way to plaster a "this is important" label on the
commit message.
Oh, here's another thought: including an explicit patch of the
pending-notes file in submissions won't work very well, since that part
of the patch will surely fail to apply if it's even a few days old.
It'll have to come in as separate text that the committer inserts into
the pending-notes file when he commits. From this perspective, it might
be a lot easier to put the notes into CVS commit messages; there'll be
fewer problems with commit collisions.
regards, tom lane
Tom Lane writes: > I agree completely, and was about to make a similar proposal. However, > I'm not entirely sure where "the release notes" actually are, nor which > is the master copy. Also, I'd prefer not to have to deal with SGML > markup for them. The release notes are in the file release.sgml. You don't really have to deal with any markup there. Look at the source under sect2 "Changes"; you only need to insert a line there. (Well, not there. A new section will be created.) Grouping this into useful categories and creating the "highlights" at the top can be done later during the usual revising and editing. > What I'd suggest is that we keep a plaintext file somewhere near the > top of the CVS tree (in doc/ perhaps) that developers append > release-notes items to as the work is completed. At the end of each > development cycle, Bruce can prepare the "nice looking" notes from that > source and then reset the file to empty for the next cycle. This (and later CVS log based ideas) don't really address my point #1: keeping users informed. You might underestimate that. Plenty of users would really like to try out development snapshots for their new projects, or see if they compile, verify new features early, or just to play around. But that's a lot harder if they don't know what's in there. Secondly, why do double work if you can just do it right the first time? We've been doing an excellent job lately about keeping the documentation current. This is really the same corner, but it's even more fundamental: If you know what changes have been made since the last release you can easily check if those changes have made it into the documentation. I'm not suggesting that we become laxer about documentation updates because of this, neither do I want strict "every patch must update the release notes" policies. Just keep in mind that at some point, when you update the documentation (meaning you feel your feature is reasonably complete to the point that you want to let it loose), add a line to the release notes to let people know it's there. That's it. -- Peter Eisentraut peter_e@gmx.net
On Fri, Feb 08, 2002 at 06:03:53PM -0500, Tom Lane wrote: > Bruce Momjian <pgman@candle.pha.pa.us> writes: > > I suppose we all thought that the change wouldn't bite anyone. > > I wasn't expecting such vocal complaints, for sure. I think the users that screamed about this would like a detailed "every user visible change" list, in addition to the highpoints Release notes. > > Tom, at the time, did you think it should be mentioned in the release > > notes? > > I can't recall if I thought about it in that way. If I had, I would > have said "yes", but I don't recall if I considered the point. I've > always made a habit of writing reasonably detailed commit messages and > then leaving it to you to decide whether a release note is needed. > > Part of the point of this discussion, I think, is just to make sure that > committers consider "should there be a release note for this change?" > every time they commit. Thinking about that, and writing down the > appropriate info immediately if a note is needed, are the critical steps. And having guidelines for the developers that describe the simple questions to ask themselves when answering 'does this deserve a release note'. It's not about advertizing: it's about documenting changes, so the DBA can grep for likely words of something breaks, such as (in this case) "array". Tom, you said 'every change is user visible'. I think, for this purpose, only things that modify existing behavior (input or output) in kind, not merely quality, are 'visible'. A patch that speeds up (or slows down!) query processing by 100 fold is certainly user visible, but not for the purposes of reporting release changes. New functionality is not 'user visible'. Ross
Peter Eisentraut <peter_e@gmx.net> writes:
> Tom Lane writes:
>> What I'd suggest is that we keep a plaintext file somewhere near the
>> top of the CVS tree (in doc/ perhaps) that developers append
>> release-notes items to as the work is completed. At the end of each
>> development cycle, Bruce can prepare the "nice looking" notes from that
>> source and then reset the file to empty for the next cycle.
> This (and later CVS log based ideas) don't really address my point #1:
> keeping users informed.
That's a valid complaint against CVS-log-based notes, since most people
probably don't have or know how to use tools like cvs2cl. I don't see
why it's an argument against my idea of a dedicated text file, though.
Such a file would be just as readily found as release.sgml, possibly
more so.
> Secondly, why do double work if you can just do it right the first time?
A fair point.
I am still concerned about the prospect of either release.sgml or
a dedicated file becoming commit bottlenecks because everyone is
constantly hitting them (and in approximately the same place, too).
However, we probably can't know how big an annoyance that will be
in practice unless we try it.
regards, tom lane
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> I suppose we all thought that the change wouldn't bite anyone.
I wasn't expecting such vocal complaints, for sure.
> Tom, at the time, did you think it should be mentioned in the release
> notes?
I can't recall if I thought about it in that way. If I had, I would
have said "yes", but I don't recall if I considered the point. I've
always made a habit of writing reasonably detailed commit messages and
then leaving it to you to decide whether a release note is needed.
Part of the point of this discussion, I think, is just to make sure that
committers consider "should there be a release note for this change?"
every time they commit. Thinking about that, and writing down the
appropriate info immediately if a note is needed, are the critical steps.
regards, tom lane
"Ross J. Reedstrom" <reedstrm@rice.edu> writes:
> I think the users that screamed about this would like a detailed "every
> user visible change" list, in addition to the highpoints Release notes.
A greppable copy of the CVS logs would satisfy that, assuming that we
maintain a reasonable standard of quality in our commit messages.
David Gould evidently managed to find my commit message about that
array_out change; but I do not know how hard it was for him to look.
Perhaps we should arrange for a nightly cvs2cl run to produce a "CVS
changes since last major release" document on the website. This might
also help answer Peter's concern about visibility of work-in-progress.
> Tom, you said 'every change is user visible'. I think, for this purpose,
> only things that modify existing behavior (input or output) in kind,
> not merely quality, are 'visible'.
I don't think that's a helpful criterion. "Does it potentially break
any application code?" might be a helpful criterion.
New features that don't pose backwards-compatibility issues probably
need a different set of criteria to decide if they merit mention in
release notes.
regards, tom lane
Tom Lane writes: > That's a valid complaint against CVS-log-based notes, since most people > probably don't have or know how to use tools like cvs2cl. I don't see > why it's an argument against my idea of a dedicated text file, though. > Such a file would be just as readily found as release.sgml, possibly > more so. Do you have a suggestion for a name and where to put the file. Will it be removed or cleared before releases? > I am still concerned about the prospect of either release.sgml or > a dedicated file becoming commit bottlenecks because everyone is > constantly hitting them (and in approximately the same place, too). There are lots of and big projects that use GNU-style ChangeLogs. Theoretically, they would all hit at the same place, but in practice this is never a problem. When an outsider submits a patch he just puts the changelog entry into a separate attachment or right into the message and the committer puts it into the right place. We can make this to work as well. If someone comes along, "hey, I just added a --foo option to pg_bar to do xyx", the patch committer simply adds a line "added --foo option to pg_bar to do xyz" to the log. All the release note items are one-liners, so this can't be too big of a deal. -- Peter Eisentraut peter_e@gmx.net
Peter Eisentraut <peter_e@gmx.net> writes:
>> Such a file would be just as readily found as release.sgml, possibly
>> more so.
> Do you have a suggestion for a name and where to put the file. Will it be
> removed or cleared before releases?
I think it should live in .../doc, same as TODO. Not picky about name.
I don't think we should remove the file; removing and re-adding it will
probably do strange things to CVS history. One could argue about
whether we even need to clear it. Might be best to ship it as-is in
the release, and then clear it *after* the next version branch.
regards, tom lane
Tom Lane writes: > I think it should live in .../doc, same as TODO. Not picky about name. > > I don't think we should remove the file; removing and re-adding it will > probably do strange things to CVS history. One could argue about > whether we even need to clear it. Might be best to ship it as-is in > the release, and then clear it *after* the next version branch. It seems that I'm going to have a hard time convincing people to put the notes into the DocBook sources right away, so in order to get this jump-started, I'll go with the text file. New changes go at the top. I guess we'll want to keep the one-liner, barely-a-sentence format for now. Not sure if we want to ship this file, but we can think about that later when we see how it develops. As for name, maybe CHANGES. You could think of it this way: Some changes may cancel each other out along the way and may not go down into "history". -- Peter Eisentraut peter_e@gmx.net
...
> It seems that I'm going to have a hard time convincing people to put the
> notes into the DocBook sources right away, so in order to get this
> jump-started, I'll go with the text file.
Why would putting notes into the DocBook sources be a problem? It is as
trivial as it can get, and it would eliminate one of the few remaining
disconnects between presentable final documentation and folks doing the
work.
I'm happy having this in DocBook, Peter would prefer it too, and it
doesn't hurt or bite hard so why would it be a problem for others?
I'm afraid I purged some of this thread from my mail, but are there
issues other than "I don't know which file to use" or "I don't
understand DocBook markup"? Both of those are easy to fix...
- Thomas
Bruce Momjian writes: > Seems there are two uses for the CHANGES file, one is to enable > developers to see what has been added to the tree since they last > looked, best solved with cvslog, No, a cvslog is in nature different from a list of user-visible changes. We're not talking about the core group of developers here that read the committers list anyway, we're talking about people that only look once in a while and want to check development progress, try out the latest features, and avoid sending in patches for things that are already done. > and second, to make it easier to > package the final HISTORY changes, which is 100x easier to do in one > shot from the cvs logs than piecemeal. There is no piecemeal. If it's all in one place you just copy it over. It's impossible to beat that. -- Peter Eisentraut peter_e@gmx.net
On Friday 15 February 2002 08:43 pm, Peter Eisentraut wrote: > Bruce Momjian writes: > > Seems there are two uses for the CHANGES file, one is to enable > > developers to see what has been added to the tree since they last > > looked, best solved with cvslog, > No, a cvslog is in nature different from a list of user-visible changes. > We're not talking about the core group of developers here that read the It almost sounds like you want something like BitKeeper, which, barring its weird license, seems tobe just the ticker. But there's that weird license..... -- Lamar Owen WGCR Internet Radio 1 Peter 4:11
Peter Eisentraut <peter_e@gmx.net> writes:
> As for name, maybe CHANGES. You could think of it this way: Some changes
> may cancel each other out along the way and may not go down into
> "history".
Sure. Or maybe RECENTCHANGES, to point out that it's not a changelist
back to the beginning of time. But I don't care much. Please create
it, and I'll start making entries...
regards, tom lane