Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ef84y-0000VF-Qx for pgsql-docs@arkaria.postgresql.org; Fri, 26 Jan 2018 17:46:21 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ef84x-00047N-Ul for pgsql-docs@arkaria.postgresql.org; Fri, 26 Jan 2018 17:46:19 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1ef7mP-00055L-QU for pgsql-docs@lists.postgresql.org; Fri, 26 Jan 2018 17:27:10 +0000 Received: from mail-wr0-x241.google.com ([2a00:1450:400c:c0c::241]) by magus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1ef7mM-00031m-76 for pgsql-docs@postgresql.org; Fri, 26 Jan 2018 17:27:09 +0000 Received: by mail-wr0-x241.google.com with SMTP id a1so1165365wri.5 for ; Fri, 26 Jan 2018 09:27:05 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=room118solutions.com; s=google; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc; bh=kNkGql/fnMxKfC1xQEEOQ4L310/lLbd+dlj3HvspOXc=; b=dKCQXQBNmdBiNrNpl6ifaK6J+ptWQObqmf+cpYw3mI80TOr316SnWwF1rE143W0AWx MT66W0seBcUWSpwSS1s3/mjVFiDiwWOrxcN+5dDS2qTEi0oJ9l8MnTl5Z4ZXtBY+qPm5 VceLZNjbgMv+dLWSKBic9Y98NMITv69mVXq4w= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc; bh=kNkGql/fnMxKfC1xQEEOQ4L310/lLbd+dlj3HvspOXc=; b=fdzjSR9pbvcPE1CiAc47rDtbCl/FfywV46m2vFkY7Q7RXKdT0CEXW6vVzYImu2ajyU deM8sJA4fDU5RnDLV9Oi627zm+IK49PRezYma0/ljoljSMXg1ew5W2a9ABcVsLNF41Hw PICYQwE9fqVGEvijutr8X6aT/LOcsFmoE9JoCT8VoTmw+Oo99k/W5Bu7yKjmXju/ny38 plRL3K70FpvJX6yS8DzCDaHUho+A4HQ790orU+f9xiz5m34snQ5xSBqaHEyxFWSWgajx +hPitfzm7fY+59HFOqHxSArHq2msR6/ZHihXTHh79aurHcZTrAaAF1OsWWXJS9pSYERu 0azQ== X-Gm-Message-State: AKwxytczZzRHWG7e0yCxwofpRyf8IAFeGszgIruLCR78pP5pC925z2HA +DKDm/7znagsgrSZ333f4/7PiamihqnNS6VKVPLDz4yp X-Google-Smtp-Source: AH8x224pJrr/syHllNYx5viIZOx7RINy21itpWuOANLFM97hKeFDO1hXNHoy2LTmkaUpK05VUYozZDZyD52cFdPycgw= X-Received: by 10.223.175.213 with SMTP id y21mr7851999wrd.135.1516987624662; Fri, 26 Jan 2018 09:27:04 -0800 (PST) MIME-Version: 1.0 Received: by 10.223.134.57 with HTTP; Fri, 26 Jan 2018 09:26:44 -0800 (PST) X-Originating-IP: [108.30.178.16] In-Reply-To: <20180126172102.GJ20836@momjian.us> References: <20171218213041.25744.8414@wrigleys.postgresql.org> <20180126002618.GA20836@momjian.us> <20180126172102.GJ20836@momjian.us> From: Jim Ryan Date: Fri, 26 Jan 2018 12:26:44 -0500 Message-ID: Subject: Re: pg_upgrade docs are confusing if PostgreSQL's versioning system/language isn't known to reader To: Bruce Momjian Cc: pgsql-docs@postgresql.org Content-Type: multipart/alternative; boundary="f403043890e47f39ba0563b1342d" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --f403043890e47f39ba0563b1342d Content-Type: text/plain; charset="UTF-8" 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 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 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 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 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 + > --f403043890e47f39ba0563b1342d Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Ah! Thank you.=C2=A0 That makes more sense.=C2=A0 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 ne= ed to use pg_upgrade when moving from 9.x to 9.y, when they actually do.=C2= =A0 Is explaining the recent versioning change outside the scope of these d= ocs?=C2=A0 If so, then perhaps a link to the versioning policy would work?= =C2=A0

Jim

On Fri, Jan 26, 2018 at 12:21 PM, Bruce Momjian <br= uce@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?=C2=A0 Aren't those considered major versions, or am I misund= erstanding?

Uh, it is confusing.=C2=A0 We switched in PG 10 from changing the _t= hird_
number for a minor release to changing the second number.=C2=A0 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.=C2=A0 I think most users wou= ld assume from
> 9.x to 10.x is a major version change.=C2=A0 The ambiguity is in 9.x t= o 9.y.=C2=A0=C2=A0

Does the patch make sense now?

-----------------------------------------------------------------= ----------

>
> Thanks,
> Jim
>
> On Thu, Jan 25, 2018 at 7:26 PM, Bruce Momjian <bruce@momjian.us> wrote:
>
>=C2=A0 =C2=A0 =C2=A0On Mon, Dec 18, 2017 at 09:30:41PM +0000, PG Doc co= mments form wrote:
>=C2=A0 =C2=A0 =C2=A0> The following documentation comment has been l= ogged on the website:
>=C2=A0 =C2=A0 =C2=A0>
>=C2=A0 =C2=A0 =C2=A0> Page: https://= www.postgresql.org/docs/9.6/static/pgupgrade.html
>=C2=A0 =C2=A0 =C2=A0> Description:
>=C2=A0 =C2=A0 =C2=A0>
>=C2=A0 =C2=A0 =C2=A0> If a reader who is unfamiliar with PostgreSQL&= amp;#39;s versioning (where 9.5
>=C2=A0 =C2=A0 =C2=A0and
>=C2=A0 =C2=A0 =C2=A0> 9.6 are considered major versions) reads the d= ocumentation, it is unclear
>=C2=A0 =C2=A0 =C2=A0if
>=C2=A0 =C2=A0 =C2=A0> they need to use pg_upgrade to migrate from 9.= 5 to 9.6, for example.
>=C2=A0 =C2=A0 =C2=A0>
>=C2=A0 =C2=A0 =C2=A0> The documentation says upgrading &quot;fro= m 9.6.3 to the current major
>=C2=A0 =C2=A0 =C2=A0release&quot;
>=C2=A0 =C2=A0 =C2=A0> requires pg_upgrade, but not &quot;from 9.= 6.2 to 9.6.3&quot;.
>=C2=A0 =C2=A0 =C2=A0>
>=C2=A0 =C2=A0 =C2=A0> The problem with that language is that the cur= rent release of PostgreSQL
>=C2=A0 =C2=A0 =C2=A0is
>=C2=A0 =C2=A0 =C2=A0> 10.=C2=A0 So is pg_upgrade required to upgrade= from 9.6.3 to current (10)
>=C2=A0 =C2=A0 =C2=A0because
>=C2=A0 =C2=A0 =C2=A0> 9 and 10 are major versions or because 9.6 and= 10.0 are major versions?
>=C2=A0 =C2=A0 =C2=A0(the
>=C2=A0 =C2=A0 =C2=A0> latter).
>=C2=A0 =C2=A0 =C2=A0>
>=C2=A0 =C2=A0 =C2=A0> It would be clearer if the documentation cover= ed all three cases:
>=C2=A0 =C2=A0 =C2=A0> 9.6.3 -&gt; 10.0.0 and 9.5.1 -&gt; 9.6= .3: pg_upgrade should be used
>=C2=A0 =C2=A0 =C2=A0> 9.6.2 -&gt; 9.6.3: pg_upgrade not needed >=C2=A0 =C2=A0 =C2=A0>
>=C2=A0 =C2=A0 =C2=A0> Or if the documentation simply noted that the = second decimal is
>=C2=A0 =C2=A0 =C2=A0considered a
>=C2=A0 =C2=A0 =C2=A0> major release.
>
>=C2=A0 =C2=A0 =C2=A0How is this attached patch?
>
>=C2=A0 =C2=A0 =C2=A0--
>=C2=A0 =C2=A0 =C2=A0=C2=A0 Bruce Momjian=C2=A0 <bruce@momjian.us>=C2=A0 =C2=A0 =C2=A0 =C2=A0 http://momjian.= us
>=C2=A0 =C2=A0 =C2=A0=C2=A0 EnterpriseDB=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0http= ://enterprisedb.com
>
>=C2=A0 =C2=A0 =C2=A0+ As you are, so once was I.=C2=A0 As I am, so you = will be. +
>=C2=A0 =C2=A0 =C2=A0+=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 Ancient Roman grave inscription +
>
>

--
=C2=A0 Bruce Momjian=C2=A0 <bruce@mo= mjian.us>=C2=A0 =C2=A0 =C2=A0 =C2=A0 http://momjian.us
=C2=A0 EnterpriseDB=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0http://enterprisedb.com
+ As you are, so once was I.=C2=A0 As I am, so you will be. +
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 Ancient Roman grave inscription +

--f403043890e47f39ba0563b1342d--