On Thu, Apr 4, 2024 at 11:23 AM Bruce Momjian <br...@momjian.us> wrote:
> On Wed, Apr 3, 2024 at 06:01:41PM -0700, David G. Johnston wrote: > > <p> > > The PostgreSQL Global Development Group supports a major version for 5 > years > > -after its initial release. After its five year anniversary, a major > version > > will > > -have one last minor release containing any fixes and will be considered > > -end-of-life (EOL) and no longer supported. > > +after its initial release. After its fifth anniversary, a major version > will > > +have one last minor release and will be considered > > +end-of-life (EOL), meaning no new bug fixes will be written for it. > > </p> > > > > # "fifth anniversary "seems more correct than "five year anniversary". > > # The fact it gets a minor release implies it receives fixes. > > # I've always had an issue with our use of the phrasing "no longer > supported". > > It seems vague when practically it just means we stop writing patches > for it. > > Whether individual community members refrain from answering questions or > > helping people on these older releases is not a project decision but a > personal > > one. Also, since we already say it is supported for 5 years it seems a > bit > > redundant to then also say "after 5 years it is unsupported". > > I went with the attached patch. I tightned up the "unsupported" part, > trying to > tie it to the fact that we don't make anymore releases for it. > > > <h2>Version Numbering</h2> > > @@ -45,11 +45,12 @@ number, e.g. 9.5.3 to 9.5.4. > > <h2>Upgrading</h2> > > > > <p> > > -Major versions usually change the internal format of the system tables. > > -These changes are often complex, so we do not maintain backward > > -compatibility of all stored data. A dump/reload of the database or use > of the > > -<a href="/docs/current/pgupgrade.html">pg_upgrade</a> module is required > > -for major upgrades. We also recommend reading the > > +Major versions need the data directory to be initialized so that the > system > > tables > > +specific to that version can be created. There are two options to then > > +migrate the user data from the old directory to the new one: a > dump/reload > > +of the database or using the > > +<a href="/docs/current/pgupgrade.html">pg_upgrade</a> module. > > +We also recommend reading the > > <a href="/docs/current/upgrading.html">upgrading</a> section of the > major > > version you are planning to upgrade to. You can upgrade from one major > version > > to another without upgrading to intervening versions, but we recommend > reading > > @@ -58,14 +59,15 @@ versions prior to doing so. > > </p> > > > > # This still talked about "stored data" when really that isn't the main > concern > > and if it was pg_upgrade wouldn't work as an option. > > # The choice to say "data directory" here seems reasonable if arguable. > But it > > implies the location of user data and we state it also contains > > version-specific system tables. It can go unsaid that they are > > version-specific because the collection as a whole and the layout of > individual > > tables can and almost certainly will change between versions. > > > > <p> > > -Minor release upgrades do not require a dump and restore; you simply > stop > > +Minor releases upgrades do not impact the data directory, only the > binaries. > > +You simply stop > > the database server, install the updated binaries, and restart the > server. > > -Such upgrades might require manual changes to complete so always read > > +However, some upgrades might require manual changes to complete so > always read > > the release notes first. > > </p> > > > > # The fact minor releases don't require dump/reload doesn't directly > preclude > > them from needing pg_upgrade and writing "Such upgrades" seems like it > could > > Minor upgrades never have required pg_upgrade. > > How about this: """ Major versions make complex changes, so the contents of the data directory cannot be maintained in a backward compatible way. A dump and restore of the databases is required, either done manually or as part of running the <a href="/docs/current/pgupgrade.html">pg_upgrade</a> server application. """ My main change here is to mirror "dump and restore" in both paragraphs and make it clear that this action is required and that the unnamed pg_dump/pg_restore tools or pg_upgrade are used in order to perform this task. Since minor version upgrades do not require "dump and restore" they need not use these tools. Also, calling pg_upgrade a module doesn't seem correct. It is found under server applications in our docs and consists solely of that program (and a bunch of manual steps) from the user's perspective. David J.
