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. > lead someone to think that. > # Data Directory seems generic enough to be understood here and since I > mention > it in the Major Version as to why data migration is needed, mentioning here > # as something not directly altered and thus precluding the data migration has > a nice symmetry. The potential need for manual changes becomes clearer as > well. > I decided your use of "data directory" was a better term and to combine the first two sentences. > <p> > -Minor releases only fix frequently-encountered bugs, <a > +Minor releases only fix bugs, <a > href="/support/security/">security</a> issues, and data corruption > problems, so such upgrades are very low risk. <em>The community > considers performing minor upgrades to be less risky than continuing to > > # Reality mostly boils down to trusting our judgement when it comes to bugs as > each one is evaluated individually. We do not promise to leave simply buggy > behavior alone in minor releases which is the only policy that would nearly > eliminate upgrade risk. We back-patch 5 year old bugs quite often which by > definition are not frequently encountered. I cannot think of a good adjective > to put there nor does one seem necessary even if I agree it reads a bit odd > otherwise. I think that has more to do with this being just the wrong > structure to get our point across. Can we pick out some statistics from our > long history of publishing minor releases to present an objective reality to > the reader to convince them to trust our track-record in this matter? I went with frequently-encountered and low risk bugs". Patch attached. -- Bruce Momjian <br...@momjian.us> https://momjian.us EDB https://enterprisedb.com Only you can decide what is important to you.
diff --git a/templates/support/versioning.html b/templates/support/versioning.html index d48e11e0..aef331a6 100644 --- a/templates/support/versioning.html +++ b/templates/support/versioning.html @@ -21,9 +21,8 @@ a release available outside of the minor release roadmap. <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 this, a final minor version will be released +and the software will then be unsupported (end-of-life). </p> <h2>Version Numbering</h2> @@ -45,16 +44,9 @@ number, e.g. 9.5.3 to 9.5.4. <h2>Upgrading</h2> <p> - <strong> - We always recommend that all users run the latest available minor - release for whatever major version is in use. - </strong> -</p> - -<p> -Major versions usually change the internal format of system tables and data -files. 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 +Major versions make complex changes, so the contents of the data directory +cannot be maintained in a backward compatible way. 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 <a href="/docs/current/upgrading.html">upgrading</a> section of the major @@ -65,18 +57,25 @@ versions prior to doing so. </p> <p> -Upgrading to a minor release does not normally require a dump and restore; you -can stop the database server, install the updated binaries, and restart the -server. For some releases, manual changes may be required to complete the -upgrade, so always read the release notes before upgrading. +Minor release upgrades do not require a dump and restore; 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 +the release notes first. </p> <p> -While upgrading will always contain some level of risk, PostgreSQL minor releases -fix only frequently-encountered bugs, <a href="/support/security/">security</a> -issues, and data corruption problems to reduce the risk associated with -upgrading. For minor releases, <em>the community considers not upgrading to be -riskier than upgrading.</em> +Minor releases only fix frequently-encountered and low-risk bugs, <a +href="/support/security/">security</a> issues, and data corruption +problems, so such upgrades are very low risk. <em>The community +considers performing minor upgrades to be less risky than continuing to +run an old minor version.</em> +</p> + +<p> + <strong> + We recommend that users always run the current minor release associated + with their major version. + </strong> </p> <h2>Releases</h2>