Bug 185788 - RELNOTES - Better explanation of PostgreSQL upgrade
RELNOTES - Better explanation of PostgreSQL upgrade
Status: CLOSED RAWHIDE
Product: Fedora Documentation
Classification: Fedora
Component: release-notes (Show other bugs)
devel
All Linux
medium Severity medium
: ---
: ---
Assigned To: Release Notes Tracker
Karsten Wade
http://fedoraproject.org/wiki/Docs/Be...
: Reopened
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2006-03-17 19:20 EST by Nicola Soranzo
Modified: 2007-04-18 13:40 EDT (History)
1 user (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2007-02-06 13:57:46 EST
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:


Attachments (Terms of Use)

  None (edit)
Description Nicola Soranzo 2006-03-17 19:20:12 EST
Actually the text is:

"Fedora Core 4 provided version 8.0 of PostgreSQL. If you upgrade an existing
Fedora system with a PostgreSQL database, you must upgrade the database to
access the data."

To me it's not clear that you have to back up _before_ upgrading. I'd rather prefer:

"The internal data storage format changed in respect to the version provided in
Fedora Core 4, PostgreSQL 8.0. Before upgrading an existing Fedora Core system
with a PostgreSQL database, you must back up the data and then restore it after
the upgrade."
Comment 1 Paul W. Frields 2006-03-17 20:16:17 EST
Just my $0.02, but the release notes are clear that to upgrade, you should visit
the PostgreSQL site to get up-to-the-minute information on how to perform the
upgrade.  The admonition is merely there to remind people that you can't just
install/upgrade FC5 and have everything work perfectly.  If there are caveats to
the process, we don't want to get in a position of having to replicate those in
the release notes.

At this point the release notes have been frozen for translation and the Web,
but they will likely "unfreeze" after FC5 release.  This is a candidate for
inclusion at that point, although my personal opinion is that the notes are
already explicit about directing users to the experts.
Comment 2 Nicola Soranzo 2006-03-20 10:40:35 EST
(In reply to comment #1)
> Just my $0.02, but the release notes are clear that to upgrade, you should visit
> the PostgreSQL site to get up-to-the-minute information on how to perform the
> upgrade.  The admonition is merely there to remind people that you can't just
> install/upgrade FC5 and have everything work perfectly.  If there are caveats to
> the process, we don't want to get in a position of having to replicate those in
> the release notes.

My proposed modification doesn't add anything new, just rephrases and clarifies
one paragraph! Also this upgrade method is used in PostgreSQL since version 6.0,
I've just checked all the release notes.

> At this point the release notes have been frozen for translation and the Web,
> but they will likely "unfreeze" after FC5 release.  This is a candidate for
> inclusion at that point, although my personal opinion is that the notes are
> already explicit about directing users to the experts.

It's correct to direct users to detailed official documentation (I suppose
that's what you mean with "experts"...), but I think this small clarification is
needed. So please add it to the release notes after the unfreezeing.
Comment 3 Karsten Wade 2006-03-23 15:30:37 EST
In reply to comment #2:

> My proposed modification doesn't add anything new, 
> just rephrases and clarifies one paragraph! Also 
> this upgrade method is used in PostgreSQL since 
> version 6.0, I've just checked all the release notes.

Regardless, it relies upon application-specific methodology that was different
in the past and could be different in the future.

Your change makes the [Tip] go from a static piece of useful content directing
users to the upstream documentation, to a piece of content that needs to be
validity checked for every future release.  Just like you checked the release
notes going back to PostgreSQL 6.0, we would have to do the same each release to
be sure the methodology was still fundamentally the same.  Considering that we
do not even have an accountable volunteer as lead writer for the database
content, I'm very hesitant to add more human-requiring procedures.

What I did instead was to bring the directions to go to the URL for upgrade
instructions into the [Tip] admonition:

http://fedoraproject.org/wiki/Docs/Beats/DatabaseServers

We already need to update that upgrade URL for (probably) each release, but it
is a single change that gets us the benefit of _all_ of the upstream content on
the subject without causing us to duplicate the content writing and publication
efforts.

Does that make sense?

> It's correct to direct users to detailed official
> documentation (I suppose that's what you mean with 
> "experts"...), but I think this small clarification is
> needed. 

Right, anything that points at postgresql.org/docs is 100% "the expert".  One is
almost never wrong pointing at the upstream content as canonical and best.

I'm closing this bug as NOTABUG because the original situation is not a defect
in the document.  However, I think bringing the URL into the admonition was a
Good Thing.  Thanks for reporting on the need to provide a stronger direction
for users.  I hope you understand why we do not want to recreate/reprint actual
procedures/directions from canonical sources when a hyperlink can do all the
work for us.
Comment 4 Nicola Soranzo 2006-03-24 10:05:52 EST
(In reply to comment #3)
> > My proposed modification doesn't add anything new, 
> > just rephrases and clarifies one paragraph! Also 
> > this upgrade method is used in PostgreSQL since 
> > version 6.0, I've just checked all the release notes.
> 
> Regardless, it relies upon application-specific methodology that was different
> in the past and could be different in the future.

It wasn't different in the past (only there's no available documentation for
versions before 6.0 to check), but could surely be different in the future.

> Your change makes the [Tip] go from a static piece of useful content directing
> users to the upstream documentation, to a piece of content that needs to be
> validity checked for every future release.

BTW, I've never asked to delete the directions to go to the URL!

> We already need to update that upgrade URL for (probably) each release, but it
> is a single change that gets us the benefit of _all_ of the upstream content on
> the subject without causing us to duplicate the content writing and publication
> efforts.

The back up/restore process is not necessary at every FC upgrade, since major
versions of PostgreSQL are released every 10-13 months. So in any case we need
to check the validity of the actual version of the statement.

> I'm closing this bug as NOTABUG because the original situation is not a defect
in the document.

Ok, but to me it's still not clear that you have to back up _before_ upgrading
Fedora, so I'll try anyway to suggest an enhancement, please consider it and let
me know. Substitute this:

"Fedora Core 4 provided version 8.0 of PostgreSQL. If you upgrade an existing
Fedora system with a PostgreSQL database, you must upgrade the database to
access the data.
To upgrade a database from a previous version of PostgreSQL, follow the
procedure described at
http://www.postgresql.org/docs/8.1/interactive/install-upgrading.html."

with:

"Before upgrading an existing Fedora Core system with a PostgreSQL database, it
could be necessary to follow the procedure described at
http://www.postgresql.org/docs/8.1/interactive/install-upgrading.html. Otherwise
the data may be not accessible by the new version of PostgreSQL."

My sentence works for all the previous versions of FC/PgSQL and works also if
the internal data format hasn't changed. Only the URL must be updated for new FC
releases.
Comment 5 Red Hat Bugzilla 2007-02-05 13:54:33 EST
REOPENED status has been deprecated. ASSIGNED with keyword of Reopened is preferred.
Comment 6 Karsten Wade 2007-02-06 13:57:46 EST
Not sure why we never incorporated the suggestion ...

I did the sane thing, which is update the source on the Wiki:

http://fedoraproject.org/wiki/Docs/Beats/DatabaseServers

It can now be reviewed and have the URL updated for the next release.

Thanks for the contribution.
Comment 7 Nicola Soranzo 2007-02-06 19:58:45 EST
Thank you, I lost hope about this ;)

Just one more thing, the Admonition is missing the closing bracket )

Note You need to log in before you can comment on or make changes to this bug.