Alpha Releases: Docs?

Josh Berkus wrote:

I think we need some kind of docs up, otherwise we'll get little
actual testing. As previously discussed, building the docs yourself
from pure source involves several complicated dependancies which
aren't available on all platforms.

Are we going to ship ChangeLog files or some such, giving that we're not
going to have release notes?

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Are we going to ship ChangeLog files or some such, giving that we're not
going to have release notes?

I still think we should be doing release notes for the Alphas. It will
limit the pain of doing release notes for the final release; they'll be
done already except formatting.

--
Josh Berkus
PostgreSQL Experts Inc.
www.pgexperts.com

Josh Berkus <josh@agliodbs.com> writes:

Are we going to ship ChangeLog files or some such, giving that we're not
going to have release notes?

I still think we should be doing release notes for the Alphas.

Are you volunteering?

regards, tom lane

Josh Berkus wrote:

Are we going to ship ChangeLog files or some such, giving that we're not
going to have release notes?

I still think we should be doing release notes for the Alphas. It
will limit the pain of doing release notes for the final release;
they'll be done already except formatting.

We are making more work for ourselves for very little benefit, ISTM.
Unless we make the alpha process very lightweight indeed, I think it
will be a net negative.

cheers

andrew

Are you volunteering?

Maybe; is there a template where I can access it?

Robert pointed out I ought to get involved anyway for 8.5 so that we can
stop having separate "release notes" and "public" versions of the new
features.

--
Josh Berkus
PostgreSQL Experts Inc.
www.pgexperts.com

On Monday 03 August 2009 23:08:51 Josh Berkus wrote:

There's another question for alpha releases: are we going to build docs?

Yes, absolutely. I'm working on making the documentation build part of the
tarball build procedure.

Either for www.postgresql.org, or for PGDATA/docs?

The web team has to figure out whether putting the docs on the web site is
worthwhile. We already have the developer docs that are rebuild on every
check-in.

On Monday 03 August 2009 23:13:27 Alvaro Herrera wrote:

Josh Berkus wrote:

I think we need some kind of docs up, otherwise we'll get little
actual testing. As previously discussed, building the docs yourself
from pure source involves several complicated dependancies which
aren't available on all platforms.

Are we going to ship ChangeLog files or some such, giving that we're not
going to have release notes?

There will still be release notes. They might not be as polished as the final
ones, but there will be a list of new things, at least.

On Tue, Aug 4, 2009 at 16:06, Peter Eisentraut<peter_e@gmx.net> wrote:

On Monday 03 August 2009 23:08:51 Josh Berkus wrote:
The web team has to figure out whether putting the docs on the web site is
worthwhile.  We already have the developer docs that are rebuild on every
check-in.

As long as the HTML files are available, we can make this happen. We
don't have the website servers set up with the full build tools, and
we don't want that :-) It is probably not going to be a terrible
amount of work, so if we are going to actually push for people to do
serious testing on the alpha releases, we should definitely get the
docs up on the website.

I don't think we should keep an archive of "old alphas" though -
that's going to leave us with insane amounts of documentation sets.
But we could have a /docs/alpha/ which would hold the latest released
alpha.

--
Magnus Hagander
Self: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

Peter Eisentraut <peter_e@gmx.net> writes:

On Monday 03 August 2009 23:13:27 Alvaro Herrera wrote:

Are we going to ship ChangeLog files or some such, giving that we're not
going to have release notes?

There will still be release notes. They might not be as polished as the final
ones, but there will be a list of new things, at least.

That would be great, but who's going to do them?

regards, tom lane

Tom Lane wrote:

Peter Eisentraut <peter_e@gmx.net> writes:

On Monday 03 August 2009 23:13:27 Alvaro Herrera wrote:

Are we going to ship ChangeLog files or some such, giving that we're not
going to have release notes?

There will still be release notes. They might not be as polished as the final
ones, but there will be a list of new things, at least.

That would be great, but who's going to do them?

It's easy, just cvs2cl and paste that in a large <pre> block.

--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

On Tuesday 04 August 2009 17:48:12 Tom Lane wrote:

Peter Eisentraut <peter_e@gmx.net> writes:

On Monday 03 August 2009 23:13:27 Alvaro Herrera wrote:

Are we going to ship ChangeLog files or some such, giving that we're not
going to have release notes?

There will still be release notes. They might not be as polished as the
final ones, but there will be a list of new things, at least.

That would be great, but who's going to do them?

I can do it. Perhaps Josh wants to get involved.

On Tue, Aug 4, 2009 at 10:48 AM, Tom Lane<tgl@sss.pgh.pa.us> wrote:

Peter Eisentraut <peter_e@gmx.net> writes:

On Monday 03 August 2009 23:13:27 Alvaro Herrera wrote:

Are we going to ship ChangeLog files or some such, giving that we're not
going to have release notes?

There will still be release notes.  They might not be as polished as the final
ones, but there will be a list of new things, at least.

That would be great, but who's going to do them?

I think the question is "who are you going to allow to do them?". I
sort of get the impression that you and Bruce have a love-hate
relationship with the release notes. On the one hand, they're a huge
time sink. On the other hand, it feels like you're not quite ready to
turn them over to anyone else. I feel like there have been some
previous offers of help (including by me) that either weren't an offer
to do quite the right thing or the offer was made at the wrong stage
of the process. I believe you told me on one occasion that they had
to all be written by a single person so that they'd be consistent...
but then, even though Bruce did the initial draft of the release
notes, you did most of the updating as we got closer to release and
more things were committed, so apparently it wasn't that critical for
one person to do it all after all.

For alpha, I think a dump of the CVS commit logs is fine if there's
not a better option. That's what Peter originally proposed, and
there's no reason to change now. But I suspect that it might be
possible to find someone who would be willing to do more than that if
they were treated nicely. For example, if someone volunteers to help
with this now, will their work be thrown out and redone by you and
Bruce "the right way" when the actual release arrives? Or will we
just revise and extend that work throughout the release cycle?

If you want to be rid of this task, then help some other people to do
it and do it well. If you want to keep doing it yourself, then dump
the CVS logs into the alpha release notes and call it good.

...Robert

Robert Haas <robertmhaas@gmail.com> writes:

On Tue, Aug 4, 2009 at 10:48 AM, Tom Lane<tgl@sss.pgh.pa.us> wrote:

That would be great, but who's going to do them?

I think the question is "who are you going to allow to do them?".

You misread that entirely. What I was pointing out was that we didn't
have a volunteer to expend the nontrivial amount of time required to
do nice notes. If you're volunteering, step right up.

(If "cvs2cl dump" is the best we can do, so be it; but I predict it
will put off a lot of potential testers. The commit messages have
always been written by hackers for hackers, not for end users.)

regards, tom lane

On Tue, Aug 4, 2009 at 11:44 AM, Tom Lane<tgl@sss.pgh.pa.us> wrote:

Robert Haas <robertmhaas@gmail.com> writes:

On Tue, Aug 4, 2009 at 10:48 AM, Tom Lane<tgl@sss.pgh.pa.us> wrote:

That would be great, but who's going to do them?

I think the question is "who are you going to allow to do them?".

You misread that entirely.  What I was pointing out was that we didn't
have a volunteer to expend the nontrivial amount of time required to
do nice notes.  If you're volunteering, step right up.

I'm willing to help if these are "8.5 release notes in process". I'm
not willing to help if they are "alpha release notes that will be
thrown away afterwards". Which is it?

...Robert

Robert Haas <robertmhaas@gmail.com> writes:

I'm willing to help if these are "8.5 release notes in process". I'm
not willing to help if they are "alpha release notes that will be
thrown away afterwards". Which is it?

That depends largely on what they look like when we get to beta,
I imagine. Are you asking for a guarantee that no one will edit
your deathless prose?

Traditionally one of the main time sinks involved in making the release
notes has been trying to give them a uniform voice, categorizing them
sensibly, weighting the space given to different topics in a way that
seems to make sense in hindsight, etc. I'd be rather surprised if notes
prepared piecemeal over a series of alpha releases didn't need work of
that sort when we get to the end. That doesn't mean the work would be
"thrown away", but it does mean it's likely to get edited.

regards, tom lane

On Tue, Aug 4, 2009 at 12:01 PM, Tom Lane<tgl@sss.pgh.pa.us> wrote:

Robert Haas <robertmhaas@gmail.com> writes:

I'm willing to help if these are "8.5 release notes in process".  I'm
not willing to help if they are "alpha release notes that will be
thrown away afterwards".  Which is it?

That depends largely on what they look like when we get to beta,
I imagine.  Are you asking for a guarantee that no one will edit
your deathless prose?

Not at all. Don't misunderstand me here: what I was worried about
(and maybe it's without any justification) is that you and/or Bruce
have ideas about how this has to be done that are so specific that
it's not even worth anyone else making an attempt. If that were the
case, then I wouldn't be very interested in working on it.

Now, on the other hand, if doing some work now incrementally over the
next couple of alpha releases will not only produce good release notes
for those alpha releases but also streamline the process of putting
together release notes for beta/final, then it sounds like a
worthwhile investment of time. In the 8.4 release cycle, this was one
of the things that held us up a bit (not a huge amount, but a bit):
all the work was done at the end, and there was a lot to do. If we
can make a start on this early, and if the start is good enough that
it requires incremental changes rather than "rm -f" then that seems
like a pretty good idea.

Traditionally one of the main time sinks involved in making the release
notes has been trying to give them a uniform voice, categorizing them
sensibly, weighting the space given to different topics in a way that
seems to make sense in hindsight, etc.  I'd be rather surprised if notes
prepared piecemeal over a series of alpha releases didn't need work of
that sort when we get to the end.  That doesn't mean the work would be
"thrown away", but it does mean it's likely to get edited.

OK, great. That sounds like exactly the sort of editing that I would
expect to be necessary.

...Robert

On Tuesday 04 August 2009 18:52:06 Robert Haas wrote:

I'm willing to help if these are "8.5 release notes in process". I'm
not willing to help if they are "alpha release notes that will be
thrown away afterwards". Which is it?

I was working on the latter assumption.

I have some reservations about the former approach. It would basically commit
us right now to having a consistent set of volunteers available every two
months within specific 1-2 day spans. Which is the sort of thing I wanted to
avoid. But if we have that commitment, then go for it.

I have some reservations about the former approach. It would basically commit
us right now to having a consistent set of volunteers available every two
months within specific 1-2 day spans. Which is the sort of thing I wanted to
avoid. But if we have that commitment, then go for it.

Can we hear from Bruce on this, as well? I think Robert is right to be
concerned that his work will be thrown away; so am I.

--
Josh Berkus
PostgreSQL Experts Inc.
www.pgexperts.com

Magnus,

I don't think we should keep an archive of "old alphas" though -
that's going to leave us with insane amounts of documentation sets.
But we could have a /docs/alpha/ which would hold the latest released
alpha.

Yes, that's perfect.

For that matter, for the release notes, I wasn't planning to have a
seperate set for every alpha. I was thinking of just creating a
*cumulative* set, with the new items for the current alpha flagged somehow.

--
Josh Berkus
PostgreSQL Experts Inc.
www.pgexperts.com