Date: Thu, 25 Jan 2018 19:26:18 -0500
From: Bruce Momjian <bruce@momjian.us>
To: jim@room118solutions.com, pgsql-docs@postgresql.org
Subject: Re: pg_upgrade docs are confusing if PostgreSQL's versioning
 system/language isn't known to reader
Message-ID: <20180126002618.GA20836@momjian.us>
References: <20171218213041.25744.8414@wrigleys.postgresql.org>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="OgqxwSJOaUobr8KG"
Content-Disposition: inline
In-Reply-To: <20171218213041.25744.8414@wrigleys.postgresql.org>
User-Agent: Mutt/1.5.23 (2014-03-12)
Precedence: bulk


--OgqxwSJOaUobr8KG
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

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 +

--OgqxwSJOaUobr8KG
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="version.diff"

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
new file mode 100644
index 055eac3..ed34a64
*** a/doc/src/sgml/ref/pgupgrade.sgml
--- b/doc/src/sgml/ref/pgupgrade.sgml
***************
*** 40,46 ****
    major version without the data dump/reload typically required for
    major version upgrades, e.g. from 9.6.3 to the current major release
    of <productname>PostgreSQL</productname>.  It is not required for minor version upgrades, e.g. from
!   9.6.2 to 9.6.3.
   </para>
  
   <para>
--- 40,46 ----
    major version without the data dump/reload typically required for
    major version upgrades, e.g. from 9.6.3 to the current major release
    of <productname>PostgreSQL</productname>.  It is not required for minor version upgrades, e.g. from
!   9.6.2 to 9.6.3 or from 10.1 to 10.2.
   </para>
  
   <para>

--OgqxwSJOaUobr8KG--