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

On Mon, Dec 18, 2017 at 09:30:41PM +0000, PG Doc comments form wrote:

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'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 "from 9.6.3 to the current major release"
requires pg_upgrade, but not "from 9.6.2 to 9.6.3".

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 -> 10.0.0 and 9.5.1 -> 9.6.3: pg_upgrade should be used
9.6.2 -> 9.6.3: pg_upgrade not needed

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

How is this attached patch?

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Hey Bruce,

Thanks for working on this, but wouldn't pg_upgrade be needed from 10.1 to
10.2? Aren't those considered major versions, or am I misunderstanding?

The source of my (and potentially others) confusion is if from 9.1 to 9.2
is considered a major version change or not. I think most users would
assume from 9.x to 10.x is a major version change. The ambiguity is in 9.x
to 9.y.

Thanks,
Jim

On Thu, Jan 25, 2018 at 7:26 PM, Bruce Momjian <bruce@momjian.us> wrote:

On Fri, Jan 26, 2018 at 12:04:17PM -0500, Jim Ryan wrote:

Hey Bruce,

Thanks for working on this, but wouldn't pg_upgrade be needed from 10.1 to
10.2?� Aren't those considered major versions, or am I misunderstanding?

Uh, it is confusing. We switched in PG 10 from changing the _third_
number for a minor release to changing the second number. The next
major release of Postgres will be PG 11.

The source of my (and potentially others) confusion is if from 9.1 to 9.2 is
considered a major version change or not.� I think most users would assume from
9.x to 10.x is a major version change.� The ambiguity is in 9.x to 9.y.��

Does the patch make sense now?

---------------------------------------------------------------------------

Thanks,
Jim

On Thu, Jan 25, 2018 at 7:26 PM, Bruce Momjian <bruce@momjian.us> wrote:

On Mon, Dec 18, 2017 at 09:30:41PM +0000, PG Doc comments form wrote:

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.

How is this attached patch?

--
� Bruce Momjian� <bruce@momjian.us>� � � � http://momjian.us
� EnterpriseDB� � � � � � � � � � � � � � �http://enterprisedb.com

+ As you are, so once was I.� As I am, so you will be. +
+� � � � � � � � � � � Ancient Roman grave inscription +

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Ah! Thank you. That makes more sense. I think this could still be
confusing for users who did not know about this change and are on 9.x,
because the docs now seemingly imply that they would not need to use
pg_upgrade when moving from 9.x to 9.y, when they actually do. Is
explaining the recent versioning change outside the scope of these docs?
If so, then perhaps a link to the versioning policy would work?

Jim

On Fri, Jan 26, 2018 at 12:21 PM, Bruce Momjian <bruce@momjian.us> wrote:

On Friday, January 26, 2018, Jim Ryan <jim@room118solutions.com> wrote:

Hey Bruce,

Thanks for working on this, but wouldn't pg_upgrade be needed from 10.1 to
10.2? Aren't those considered major versions, or am I misunderstanding?

The source of my (and potentially others) confusion is if from 9.1 to 9.2
is considered a major version change or not. I think most users would
assume from 9.x to 10.x is a major version change. The ambiguity is in 9.x
to 9.y.

Which is why we changed ;)

Starting with 10 the one and only value after the decimal is a minor
version bug fix release. The next major version will be 11.

Of versions beginning with 9 there were 7 major versions - 9.0 to 9.6; the
third position value denoted the minor bug fix release.

pg-upgrade is only required for upgrading between major versions.

On our homeoage we list every major release that is currently supported.

David J.

On Fri, Jan 26, 2018 at 11:35:09AM -0700, David G. Johnston wrote:

On Friday, January 26, 2018, Jim Ryan <jim@room118solutions.com> wrote:

Hey Bruce,

Thanks for working on this, but wouldn't pg_upgrade be needed from 10.1 to
10.2?� Aren't those considered major versions, or am I misunderstanding?

The source of my (and potentially others) confusion is if from 9.1 to 9.2
is considered a major version change or not.� I think most users would
assume from 9.x to 10.x is a major version change.� The ambiguity is in 9.x
to 9.y.��

Which is why we changed ;)

Starting with 10 the one and only value after the decimal is a minor version
bug fix release.� The next major version will be 11.

Of versions beginning with 9 there were 7 major versions - 9.0 to 9.6; the
third position value denoted the minor bug fix release.

pg-upgrade is only required for upgrading between major versions.

On our homeoage we list every major release that is currently supported.

I decided I needed to be more explicit about the major version numbers
so I have added major and minor examples for the 9.6.x series and 10.x
series releases. Patch attached.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

On Sat, Jan 27, 2018 at 8:05 AM, Bruce Momjian <bruce@momjian.us> wrote:

I decided I needed to be more explicit about the major version numbers
so I have added major and minor examples for the 9.6.x series and 10.x
series releases. Patch attached.

​Thanks!​

​+1

​David J.

This looks great. Thanks for working on it.

Jim

On Sat, Jan 27, 2018 at 10:05 AM, Bruce Momjian <bruce@momjian.us> wrote:

On Mon, Jan 29, 2018 at 09:31:46PM -0500, Jim Ryan wrote:

This looks great.� Thanks for working on it.

Done.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +