On Tue, Apr 2, 2024 at 1:47 PM Bruce Momjian <br...@momjian.us> wrote:
> On Tue, Apr 2, 2024 at 11:34:46AM +0200, Magnus Hagander wrote: > > Okay, I changed "superseded" to "old", and changed "latest" to > "current", patch attached. > > I took a pass at this and found a few items of note. Changes on top of Bruce's patch. diff --git a/templates/support/versioning.html b/templates/support/versioning.html index 0ed79f4f..d4762967 100644 --- a/templates/support/versioning.html +++ b/templates/support/versioning.html @@ -21,9 +21,9 @@ 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 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". <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 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. <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? David J.
