pg_upgrade docs are confusing if PostgreSQL's versioning system/language isn't known to reader

From: PG Doc comments form <noreply(at)postgresql(dot)org>
To: pgsql-docs(at)postgresql(dot)org
Cc: jim(at)room118solutions(dot)com
Subject: pg_upgrade docs are confusing if PostgreSQL's versioning system/language isn't known to reader
Date: 2017-12-18 21:30:41
Message-ID: 20171218213041.25744.8414@wrigleys.postgresql.org
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/9.6/static/pgupgrade.html
Description:

If a reader who is unfamiliar with PostgreSQL&#39;s versioning (where 9.5 and
9.6 are considered major versions) reads the documentation, it is unclear if
they need to use pg_upgrade to migrate from 9.5 to 9.6, for example.

The documentation says upgrading &quot;from 9.6.3 to the current major release&quot;
requires pg_upgrade, but not &quot;from 9.6.2 to 9.6.3&quot;.

The problem with that language is that the current release of PostgreSQL is
10. So is pg_upgrade required to upgrade from 9.6.3 to current (10) because
9 and 10 are major versions or because 9.6 and 10.0 are major versions? (the
latter).

It would be clearer if the documentation covered all three cases:
9.6.3 -&gt; 10.0.0 and 9.5.1 -&gt; 9.6.3: pg_upgrade should be used
9.6.2 -&gt; 9.6.3: pg_upgrade not needed

Or if the documentation simply noted that the second decimal is considered a
major release.

Thanks for PostgreSQL!

Jim

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Peter Eisentraut 2017-12-19 20:20:38 remove endterms and title ids
Previous Message Peter Eisentraut 2017-12-18 21:14:13 Re: Typo