Обсуждение: pg_upgrade docs are confusing if PostgreSQL's versioningsystem/language isn't known to reader

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.

Thanks for PostgreSQL! 

Jim

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 +

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'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 +
> 
> 

-- 
  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.  

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 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 +