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

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(at)momjian(dot)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(at)momjian(dot)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(at)momjian(dot)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(at)momjian(dot)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 +
>