Reports on obsolete Postgres versions

On Mon, Mar 11, 2024 at 04:37:49PM -0400, Bruce Momjian wrote:

https://www.postgresql.org/support/versioning/

This web page should correct the idea that "upgrades are more risky than
staying with existing versions". Is there more we can do? Should we
have a more consistent response for such reporters?

I've read that the use of the term "minor release" can be confusing. While
the versioning page clearly describes what is eligible for a minor release,
not everyone reads it, so I suspect that many folks think there are new
features, etc. in minor releases. I think a "minor release" of Postgres is
more similar to what other projects would call a "patch version."

--
Nathan Bossart
Amazon Web Services: https://aws.amazon.com

On Mon, Mar 11, 2024 at 04:12:04PM -0500, Nathan Bossart wrote:

On Mon, Mar 11, 2024 at 04:37:49PM -0400, Bruce Momjian wrote:

https://www.postgresql.org/support/versioning/

This web page should correct the idea that "upgrades are more risky than
staying with existing versions". Is there more we can do? Should we
have a more consistent response for such reporters?

I've read that the use of the term "minor release" can be confusing. While
the versioning page clearly describes what is eligible for a minor release,
not everyone reads it, so I suspect that many folks think there are new
features, etc. in minor releases. I think a "minor release" of Postgres is
more similar to what other projects would call a "patch version."

Well, we do say:

While upgrading will always contain some level of risk, PostgreSQL
minor releases fix only frequently-encountered bugs, security issues,
and data corruption problems to reduce the risk associated with
upgrading. For minor releases, the community considers not upgrading to
be riskier than upgrading.

but that is far down the page. Do we need to improve this?

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On Mon, Mar 11, 2024 at 4:38 PM Bruce Momjian <bruce@momjian.us> wrote:

https://www.postgresql.org/support/versioning/

This web page should correct the idea that "upgrades are more risky than
staying with existing versions". Is there more we can do? Should we have
a more consistent response for such reporters?

It could be helpful to remove this sentence:

"Upgrading to a minor release does not normally require a dump and restore"

While technically true, "not normally" is quite the understatement, as the
true answer is "never" or at least "not in the last few decades". I have a
hard time even imagining a scenario that would require a minor revision to
do a dump and restore - surely, that in itself would warrant a major
release?

It would be a crazy idea to report something in the logs if a major
version is run after a certain date, since we know the date when major
versions will become unsupported.

Could indeed be useful to spit something out at startup. Heck, even minor
versions are fairly regular now. Sure would be nice to be able to point a
client at the database and say "See? Even Postgres itself thinks you should
upgrade from 11.3!!" (totally made up example, not at all related to an
actual production system /sarcasm)

Cheers,
Greg

On Mon, Mar 11, 2024 at 05:17:13PM -0400, Bruce Momjian wrote:

On Mon, Mar 11, 2024 at 04:12:04PM -0500, Nathan Bossart wrote:

I've read that the use of the term "minor release" can be confusing. While
the versioning page clearly describes what is eligible for a minor release,
not everyone reads it, so I suspect that many folks think there are new
features, etc. in minor releases. I think a "minor release" of Postgres is
more similar to what other projects would call a "patch version."

Well, we do say:

While upgrading will always contain some level of risk, PostgreSQL
minor releases fix only frequently-encountered bugs, security issues,
and data corruption problems to reduce the risk associated with
upgrading. For minor releases, the community considers not upgrading to
be riskier than upgrading.

but that is far down the page. Do we need to improve this?

I think making that note more visible would certainly be an improvement.

--
Nathan Bossart
Amazon Web Services: https://aws.amazon.com

On 12 Mar 2024, at 02:37, Nathan Bossart <nathandbossart@gmail.com> wrote:

On Mon, Mar 11, 2024 at 05:17:13PM -0400, Bruce Momjian wrote:

On Mon, Mar 11, 2024 at 04:12:04PM -0500, Nathan Bossart wrote:

I've read that the use of the term "minor release" can be confusing. While
the versioning page clearly describes what is eligible for a minor release,
not everyone reads it, so I suspect that many folks think there are new
features, etc. in minor releases. I think a "minor release" of Postgres is
more similar to what other projects would call a "patch version."

Well, we do say:

While upgrading will always contain some level of risk, PostgreSQL
minor releases fix only frequently-encountered bugs, security issues,
and data corruption problems to reduce the risk associated with
upgrading. For minor releases, the community considers not upgrading to
be riskier than upgrading.

but that is far down the page. Do we need to improve this?

I think making that note more visible would certainly be an improvement.

We have this almost at the top of the page, which IMHO isn't a very good
description about what a minor version is:

Each major version receives bug fixes and, if need be, security fixes
that are released at least once every three months in what we call a
"minor release."

Maybe we can rewrite that sentence to properly document what a minor is (bug
fixes *and* security fixes) with a small blurb about the upgrade risk?

(Adding Jonathan in CC: who is good at website copy).

--
Daniel Gustafsson

Hi,

On Mon, Mar 11, 2024 at 05:17:13PM -0400, Bruce Momjian wrote:

On Mon, Mar 11, 2024 at 04:12:04PM -0500, Nathan Bossart wrote:

On Mon, Mar 11, 2024 at 04:37:49PM -0400, Bruce Momjian wrote:

https://www.postgresql.org/support/versioning/

This web page should correct the idea that "upgrades are more risky than
staying with existing versions". Is there more we can do? Should we
have a more consistent response for such reporters?

I've read that the use of the term "minor release" can be confusing. While
the versioning page clearly describes what is eligible for a minor release,
not everyone reads it, so I suspect that many folks think there are new
features, etc. in minor releases. I think a "minor release" of Postgres is
more similar to what other projects would call a "patch version."

Well, we do say:

While upgrading will always contain some level of risk, PostgreSQL
minor releases fix only frequently-encountered bugs, security issues,
and data corruption problems to reduce the risk associated with
upgrading. For minor releases, the community considers not upgrading to
be riskier than upgrading.

but that is far down the page. Do we need to improve this?

I liked the statement from Laurenz a while ago on his blog
(paraphrased): "Upgrading to the latest patch release does not require
application testing or recertification". I am not sure we want to put
that into the official page (or maybe tone down/qualify it a bit), but I
think a lot of users stay on older minor versions because they dread
their internal testing policies.

The other thing that could maybe be made a bit better is the fantastic
patch release schedule, which however is buried in the "developer
roadmap". I can see how this was useful years ago, but I think this page
should be moved to the end-user part of the website, and maybe (also)
integrated into the support/versioning page?

Michael

but that is far down the page. Do we need to improve this?

I liked the statement from Laurenz a while ago on his blog
(paraphrased): "Upgrading to the latest patch release does not require
application testing or recertification". I am not sure we want to put
that into the official page (or maybe tone down/qualify it a bit), but I
think a lot of users stay on older minor versions because they dread
their internal testing policies.

I think we need a more conservative language since a minor release might fix a
planner bug that someone's app relied on and their plans will be worse after
upgrading. While rare, it can for sure happen so the official wording should
probably avoid such bold claims.

The other thing that could maybe be made a bit better is the fantastic
patch release schedule, which however is buried in the "developer
roadmap". I can see how this was useful years ago, but I think this page
should be moved to the end-user part of the website, and maybe (also)
integrated into the support/versioning page?

Fair point.

--
Daniel Gustafsson

On 3/12/24 3:56 AM, Daniel Gustafsson wrote:

but that is far down the page. Do we need to improve this?

I liked the statement from Laurenz a while ago on his blog
(paraphrased): "Upgrading to the latest patch release does not require
application testing or recertification". I am not sure we want to put
that into the official page (or maybe tone down/qualify it a bit), but I
think a lot of users stay on older minor versions because they dread
their internal testing policies.

I think we need a more conservative language since a minor release might fix a
planner bug that someone's app relied on and their plans will be worse after
upgrading. While rare, it can for sure happen so the official wording should
probably avoid such bold claims.

The other thing that could maybe be made a bit better is the fantastic
patch release schedule, which however is buried in the "developer
roadmap". I can see how this was useful years ago, but I think this page
should be moved to the end-user part of the website, and maybe (also)
integrated into the support/versioning page?

Fair point.

Both of the above points show inconsistency in how PG uses the terms
"minor" and "patch" today.

It's not just roadmaps and release pages where we mix up these terms
either, it's even in user-facing SQL and libpq routines: both
PQserverVersion and current_setting('server_version_num') return the
patch release version in the numeric patch field, rather than the
numeric minor field (which is always 0).

In my view, the best thing would be to move toward consistently using
the word "patch" and moving away from the word "minor" for the
PostgreSQL quarterly maintenance updates.

-Jeremy

--
http://about.me/jeremy_schneider

On Wed, Mar 13, 2024 at 09:21:27AM -0700, Jeremy Schneider wrote:

It's not just roadmaps and release pages where we mix up these terms
either, it's even in user-facing SQL and libpq routines: both
PQserverVersion and current_setting('server_version_num') return the
patch release version in the numeric patch field, rather than the
numeric minor field (which is always 0).

In my view, the best thing would be to move toward consistently using
the word "patch" and moving away from the word "minor" for the
PostgreSQL quarterly maintenance updates.

I think "minor" is a better term since it contrasts with "major". We
don't actually supply patches to upgrade minor versions.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On Wed, Mar 13, 2024 at 1:12 PM Bruce Momjian <bruce@momjian.us> wrote:

On Wed, Mar 13, 2024 at 09:21:27AM -0700, Jeremy Schneider wrote:

It's not just roadmaps and release pages where we mix up these terms
either, it's even in user-facing SQL and libpq routines: both
PQserverVersion and current_setting('server_version_num') return the
patch release version in the numeric patch field, rather than the
numeric minor field (which is always 0).

In my view, the best thing would be to move toward consistently using
the word "patch" and moving away from the word "minor" for the
PostgreSQL quarterly maintenance updates.

I think "minor" is a better term since it contrasts with "major". We
don't actually supply patches to upgrade minor versions.

I tend to agree with Bruce, and major/minor seems to be the more
common usage within the industry; iirc, debian, ubuntu, gnome, suse,
and mariadb all use that nomenclature; and ISTR some distro's who
release packaged versions of postgres with custom patches applied (ie
12.4-2 for postgres 12.4 patchlevel 2).

BTW, as a reminder, we do have this statement, in bold, in the
"upgrading" section of the versioning page:
"We always recommend that all users run the latest available minor
release for whatever major version is in use." There is actually
several other phrases and wording on that page that could probably be
propagated as replacement language in some of these other areas.

Robert Treat
https://xzilla.net

Robert Treat <rob@xzilla.net> writes:

On Wed, Mar 13, 2024 at 1:12 PM Bruce Momjian <bruce@momjian.us> wrote:

On Wed, Mar 13, 2024 at 09:21:27AM -0700, Jeremy Schneider wrote:

In my view, the best thing would be to move toward consistently using
the word "patch" and moving away from the word "minor" for the
PostgreSQL quarterly maintenance updates.

I think "minor" is a better term since it contrasts with "major". We
don't actually supply patches to upgrade minor versions.

I tend to agree with Bruce, and major/minor seems to be the more
common usage within the industry; iirc, debian, ubuntu, gnome, suse,
and mariadb all use that nomenclature; and ISTR some distro's who
release packaged versions of postgres with custom patches applied (ie
12.4-2 for postgres 12.4 patchlevel 2).

Agreed, we would probably add confusion not reduce it if we were to
change our longstanding nomenclature for this.

I'm +1 on rewriting these documentation pages though. Seems like
they could do with a whole fresh start rather than just tweaks
around the edges --- what we've got now is an accumulation of such
tweaks.

regards, tom lane

On 3/13/24 11:21 AM, Tom Lane wrote:

Robert Treat <rob@xzilla.net> writes:

On Wed, Mar 13, 2024 at 1:12 PM Bruce Momjian <bruce@momjian.us> wrote:

On Wed, Mar 13, 2024 at 09:21:27AM -0700, Jeremy Schneider wrote:

In my view, the best thing would be to move toward consistently using
the word "patch" and moving away from the word "minor" for the
PostgreSQL quarterly maintenance updates.

I think "minor" is a better term since it contrasts with "major". We
don't actually supply patches to upgrade minor versions.

I tend to agree with Bruce, and major/minor seems to be the more
common usage within the industry; iirc, debian, ubuntu, gnome, suse,
and mariadb all use that nomenclature; and ISTR some distro's who
release packaged versions of postgres with custom patches applied (ie
12.4-2 for postgres 12.4 patchlevel 2).

Agreed, we would probably add confusion not reduce it if we were to
change our longstanding nomenclature for this.

"Longstanding nomenclature"??

Before v10, the quarterly maintenance updates were unambiguously and
always called patch releases

I don't understand the line of thinking here

Bruce started this whole thread because of "an increasing number of
bug/problem reports on obsolete Postgres versions"

Across the industry the word "minor" often implies a release that will
be maintained, and I'm trying to point out that the change in v10 to
change terminology from "patch" to "minor" actually might be part of
what's responsible for the increasing number of bug reports on old patch
releases, because people don't understand that patch releases are the
way those bugfixes were already delivered.

Just taking MySQL as an example, it's clear that a "minor" like 5.7 is a
full blown release that gets separate patches from 5.6 - so I don't
understand how we're making an argument it's the opposite?

-Jeremy

--
http://about.me/jeremy_schneider

Jeremy Schneider <schneider@ardentperf.com> writes:

On 3/13/24 11:21 AM, Tom Lane wrote:

Agreed, we would probably add confusion not reduce it if we were to
change our longstanding nomenclature for this.

Before v10, the quarterly maintenance updates were unambiguously and
always called patch releases

I think that's highly revisionist history. I've always called them
minor releases, and I don't recall other people using different
terminology. I believe the leadoff text on

https://www.postgresql.org/support/versioning/

is much older than when we switched from two-part major version
numbers to one-part major version numbers.

regards, tom lane

On Mar 13, 2024, at 11:39 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Jeremy Schneider <schneider@ardentperf.com> writes:

On 3/13/24 11:21 AM, Tom Lane wrote:
Agreed, we would probably add confusion not reduce it if we were to
change our longstanding nomenclature for this.

Before v10, the quarterly maintenance updates were unambiguously and
always called patch releases

I think that's highly revisionist history. I've always called them
minor releases, and I don't recall other people using different
terminology. I believe the leadoff text on

https://www.postgresql.org/support/versioning/

is much older than when we switched from two-part major version
numbers to one-part major version numbers.

Huh, that wasn’t what I expected. I only started (in depth) working with PG around 9.6 and I definitely thought of “6” as the minor version. This is an interesting mailing list thread.

-Jeremy

Sent from my TI-83

On Wed, Mar 13, 2024 at 02:21:20PM -0400, Tom Lane wrote:

I'm +1 on rewriting these documentation pages though. Seems like
they could do with a whole fresh start rather than just tweaks
around the edges --- what we've got now is an accumulation of such
tweaks.

If no one else volunteers, I could probably give this a try once v17 is
frozen.

--
Nathan Bossart
Amazon Web Services: https://aws.amazon.com

On Tue, 2024-03-12 at 11:56 +0100, Daniel Gustafsson wrote:

I liked the statement from Laurenz a while ago on his blog
(paraphrased): "Upgrading to the latest patch release does not require
application testing or recertification". I am not sure we want to put
that into the official page (or maybe tone down/qualify it a bit), but I
think a lot of users stay on older minor versions because they dread
their internal testing policies.

I think we need a more conservative language since a minor release might fix a
planner bug that someone's app relied on and their plans will be worse after
upgrading.  While rare, it can for sure happen so the official wording should
probably avoid such bold claims.

I think we are pretty conservative with backpatching changes to the
optimizer that could destabilize existing plans.

I feel quite strongly that we should not use overly conservative language
there. If people feel that they have to test their applications for new
minor releases, the only effect will be that they won't install minor releases.
Installing a minor release should be as routine as the operating system
patches that many companies apply automatically during weekend maintenance
windows. They can also introduce bugs, and everybody knows and accepts that.

Yours,
Laurenz Albe

On Wed, Mar 13, 2024 at 3:05 PM Laurenz Albe <laurenz.albe@cybertec.at> wrote:

I think we are pretty conservative with backpatching changes to the
optimizer that could destabilize existing plans.

We have gotten better about that, which is good.

I feel quite strongly that we should not use overly conservative language
there. If people feel that they have to test their applications for new
minor releases, the only effect will be that they won't install minor releases.
Installing a minor release should be as routine as the operating system
patches that many companies apply automatically during weekend maintenance
windows. They can also introduce bugs, and everybody knows and accepts that.

I don't agree with this. If we tell people that they don't need to
test their applications after an upgrade, I do not think that the
result will be that they skip the testing and everything works
perfectly. I think that the result will be that we lose all
credibility. Nobody who has been working on computers for longer than
a week is going to believe that a software upgrade can't break
anything, and someone whose entire business depends on things not
breaking is going to want to validate that they haven't. And they're
not wrong to think that way, either.

I think that whatever we say here should focus on what we try to do or
guarantee, not on what actions we think users ought to take, never
mind must take. We can say that we try to avoid making any changes
upon which an application might be relying -- but there surely is some
weasel-wording there, because we have made such changes before in the
name of security, and sometimes to fix bugs, and we will likely to do
so again in the future. But it's not for us to decide how much testing
is warranted. It's the user's system, not ours.

In the end, while I certainly don't mind improving the web page, I
think that a lot of what we're seeing here probably has to do with the
growing popularity and success of PostgreSQL. If you have more people
using your software, you're also going to have more people using
out-of-date versions of your software.

--
Robert Haas
EDB: http://www.enterprisedb.com

On 13.03.24 18:12, Bruce Momjian wrote:

On Wed, Mar 13, 2024 at 09:21:27AM -0700, Jeremy Schneider wrote:

It's not just roadmaps and release pages where we mix up these terms
either, it's even in user-facing SQL and libpq routines: both
PQserverVersion and current_setting('server_version_num') return the
patch release version in the numeric patch field, rather than the
numeric minor field (which is always 0).

In my view, the best thing would be to move toward consistently using
the word "patch" and moving away from the word "minor" for the
PostgreSQL quarterly maintenance updates.

I think "minor" is a better term since it contrasts with "major". We
don't actually supply patches to upgrade minor versions.

There are potentially different adjectives that could apply to "version"
and "release".

The version numbers can be called major and minor, because that just
describes their ordering and significance.

But I do agree that "minor release" isn't quite as clear, because one
could also interpret that as "a release, but a bit smaller this time".
(Also might not translate well, since "minor" and "small" could
translate to the same thing.)

One could instead, for example, describe those as "maintenance releases":

"Are you on the latest maintenance release? Why not? Are you not
maintaining your database?"

That carries much more urgency than the same with "minor".

A maintenance release corresponds to an increase in the minor version
number. It's still tied together, but has different terminology.

The last news item reads:

"The PostgreSQL Global Development Group has released an update to all
supported versions of PostgreSQL"

which has no urgency, but consider

"The PostgreSQL Global Development Group has published maintenance
releases to all supported versions of PostgreSQL"

On Thu, Mar 14, 2024 at 10:15:18AM -0400, Robert Haas wrote:

I think that whatever we say here should focus on what we try to do or
guarantee, not on what actions we think users ought to take, never
mind must take. We can say that we try to avoid making any changes
upon which an application might be relying -- but there surely is some
weasel-wording there, because we have made such changes before in the
name of security, and sometimes to fix bugs, and we will likely to do
so again in the future. But it's not for us to decide how much testing
is warranted. It's the user's system, not ours.

Yes, good point, let's tell whem what our goals are and they can decide
what testing they need.

In the end, while I certainly don't mind improving the web page, I
think that a lot of what we're seeing here probably has to do with the
growing popularity and success of PostgreSQL. If you have more people
using your software, you're also going to have more people using
out-of-date versions of your software.

Yeah, probably, and we recently end-of-life'ed PG 11.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On Thu, Mar 14, 2024 at 10:46:28PM -0400, Bruce Momjian wrote:

In the end, while I certainly don't mind improving the web page, I
think that a lot of what we're seeing here probably has to do with the
growing popularity and success of PostgreSQL. If you have more people
using your software, you're also going to have more people using
out-of-date versions of your software.

Yeah, probably, and we recently end-of-life'ed PG 11.

In a way it is that we had more users during the PG 10/11 period than
before that, and those people aren't upgrading as quickly.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On 14 Mar 2024, at 16:48, Peter Eisentraut <peter@eisentraut.org> wrote:
On 13.03.24 18:12, Bruce Momjian wrote:

I think "minor" is a better term since it contrasts with "major". We
don't actually supply patches to upgrade minor versions.

There are potentially different adjectives that could apply to "version" and "release".

The version numbers can be called major and minor, because that just describes their ordering and significance.

But I do agree that "minor release" isn't quite as clear, because one could also interpret that as "a release, but a bit smaller this time". (Also might not translate well, since "minor" and "small" could translate to the same thing.)

Some of the user confusion likely stems from us using the same nomenclature as
SemVer, but for different things. SemVer has become very widely adopted, to
the point where it's almost assumed by many, so maybe we need to explicitly
state that we *don't* use SemVer (we don't mention that anywhere in the docs or
on the website).

One could instead, for example, describe those as "maintenance releases":

That might indeed be a better name for what we provide.

--
Daniel Gustafsson

On Fri, Mar 15, 2024 at 11:17:53AM +0100, Daniel Gustafsson wrote:

On 14 Mar 2024, at 16:48, Peter Eisentraut <peter@eisentraut.org> wrote:
One could instead, for example, describe those as "maintenance releases":

That might indeed be a better name for what we provide.

+1

On 3/15/24 3:17 AM, Daniel Gustafsson wrote:

On 14 Mar 2024, at 16:48, Peter Eisentraut <peter@eisentraut.org> wrote:
On 13.03.24 18:12, Bruce Momjian wrote:

I think "minor" is a better term since it contrasts with "major". We
don't actually supply patches to upgrade minor versions.

There are potentially different adjectives that could apply to "version" and "release".

The version numbers can be called major and minor, because that just describes their ordering and significance.

But I do agree that "minor release" isn't quite as clear, because one could also interpret that as "a release, but a bit smaller this time". (Also might not translate well, since "minor" and "small" could translate to the same thing.)

Some of the user confusion likely stems from us using the same nomenclature as
SemVer, but for different things. SemVer has become very widely adopted, to
the point where it's almost assumed by many, so maybe we need to explicitly
state that we *don't* use SemVer (we don't mention that anywhere in the docs or
on the website).

Semantic Versioning was definitely part of what led to my confusion
up-thread here. I was also mistaken in what I said up-thread about
MySQL, who also calls "5.7" the "major" version.

One could instead, for example, describe those as "maintenance releases":

That might indeed be a better name for what we provide.

The latest PostgreSQL news item uses the word "update" and seems pretty
well written in this area already (at least to me)

Also I just confirmed, the bug reporting form also seems well written:

"Make sure you are running the latest available minor release for your
major version before reporting a bug. The current list of supported
versions is 16.2, 15.6, 14.11, 13.14, 12.18."

This all looks good, but I do still agree that a gradual shift toward
saying "maintenance update" instead of "minor" might still promote more
clarity in the long run?

-Jeremy

--
http://about.me/jeremy_schneider

On Wed, Mar 13, 2024 at 02:04:16PM -0400, Robert Treat wrote:

I tend to agree with Bruce, and major/minor seems to be the more
common usage within the industry; iirc, debian, ubuntu, gnome, suse,
and mariadb all use that nomenclature; and ISTR some distro's who
release packaged versions of postgres with custom patches applied (ie
12.4-2 for postgres 12.4 patchlevel 2).

BTW, as a reminder, we do have this statement, in bold, in the
"upgrading" section of the versioning page:
"We always recommend that all users run the latest available minor
release for whatever major version is in use." There is actually
several other phrases and wording on that page that could probably be
propagated as replacement language in some of these other areas.

I ended up writing the attached doc patch. I found that some or our
text was overly-wordy, causing the impact of what we were trying to say
to be lessened. We might want to go farther than this patch, but I
think it is an improvement.

I also moved the <strong> text to the bottom of the section ---
previously, our <strong> wording referenced minor releases, then we
talked about major releases, and then minor releases. This gives a more
natural flow.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On 2 Apr 2024, at 00:56, Bruce Momjian <bruce@momjian.us> wrote:

I ended up writing the attached doc patch. I found that some or our
text was overly-wordy, causing the impact of what we were trying to say
to be lessened. We might want to go farther than this patch, but I
think it is an improvement.

Agreed, this is an good incremental improvement over what we have.

I also moved the <strong> text to the bottom of the section

+1

A few small comments:

+considers performing minor upgrades to be less risky than continuing to
+run superseded minor versions.</em>

I think "superseded minor versions" could be unnecessarily complicated for
non-native speakers, I consider myself fairly used to reading english but still
had to spend a few extra (brain)cycles parsing the meaning of it in this
context.

+ We recommend that users always run the latest minor release associated

Or perhaps "current minor release" which is the term we use in the table below
on the same page?

--
Daniel Gustafsson

On Wed, Mar 13, 2024 at 7:47 PM Jeremy Schneider <schneider@ardentperf.com>
wrote:

On Mar 13, 2024, at 11:39 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Jeremy Schneider <schneider@ardentperf.com> writes:

On 3/13/24 11:21 AM, Tom Lane wrote:
Agreed, we would probably add confusion not reduce it if we were to
change our longstanding nomenclature for this.

Before v10, the quarterly maintenance updates were unambiguously and
always called patch releases

I think that's highly revisionist history. I've always called them
minor releases, and I don't recall other people using different
terminology. I believe the leadoff text on

https://www.postgresql.org/support/versioning/

is much older than when we switched from two-part major version
numbers to one-part major version numbers.

Huh, that wasn’t what I expected. I only started (in depth) working with
PG around 9.6 and I definitely thought of “6” as the minor version. This is
an interesting mailing list thread.

That common misunderstanding was, in fact, one of the reasons to go to
two-part version numbers instead of 3. Because people did not realize that
the full 9.6 digit was the major version, and thus what was maintained and
such.

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/&gt;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/&gt;

On Tue, Apr 2, 2024 at 9:24 AM Daniel Gustafsson <daniel@yesql.se> wrote:

On 2 Apr 2024, at 00:56, Bruce Momjian <bruce@momjian.us> wrote:

I ended up writing the attached doc patch. I found that some or our
text was overly-wordy, causing the impact of what we were trying to say
to be lessened. We might want to go farther than this patch, but I
think it is an improvement.

Agreed, this is an good incremental improvement over what we have.

I also moved the <strong> text to the bottom of the section

+1

A few small comments:

+considers performing minor upgrades to be less risky than continuing to
+run superseded minor versions.</em>

I think "superseded minor versions" could be unnecessarily complicated for
non-native speakers, I consider myself fairly used to reading english but
still
had to spend a few extra (brain)cycles parsing the meaning of it in this
context.

+ We recommend that users always run the latest minor release associated

Or perhaps "current minor release" which is the term we use in the table
below
on the same page?

I do like the term "current" better. It conveys (at least a bit) that we
really consider all the older ones to be, well, obsolete. The difference
"current vs obsolete" is stronger than "latest vs not quite latest".

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/&gt;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/&gt;

On Tue, Apr 2, 2024 at 11:34:46AM +0200, Magnus Hagander wrote:

On Tue, Apr 2, 2024 at 9:24 AM Daniel Gustafsson <daniel@yesql.se> wrote:
A few small comments:

+considers performing minor upgrades to be less risky than continuing to
+run superseded minor versions.</em>

I think "superseded minor versions" could be unnecessarily complicated for
non-native speakers, I consider myself fairly used to reading english but
still
had to spend a few extra (brain)cycles parsing the meaning of it in this
context.

+ We recommend that users always run the latest minor release associated

Or perhaps "current minor release" which is the term we use in the table
below
on the same page?

I do like the term "current"  better. It conveys (at least a bit) that we
really consider all the older ones to be, well, obsolete. The difference
"current vs obsolete" is stronger than "latest vs not quite latest".

Okay, I changed "superseded" to "old", and changed "latest" to
"current", patch attached.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On 2 Apr 2024, at 22:46, Bruce Momjian <bruce@momjian.us> wrote:
On Tue, Apr 2, 2024 at 11:34:46AM +0200, Magnus Hagander wrote:

I do like the term "current" better. It conveys (at least a bit) that we
really consider all the older ones to be, well, obsolete. The difference
"current vs obsolete" is stronger than "latest vs not quite latest".

Okay, I changed "superseded" to "old", and changed "latest" to
"current", patch attached.

+1, LGTM

--
Daniel Gustafsson

On Tue, Apr 2, 2024 at 1:47 PM Bruce Momjian <bruce@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.

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 <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On Thu, Apr 4, 2024 at 11:23 AM Bruce Momjian <bruce@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.

On Thu, Apr 4, 2024 at 12:27:32PM -0700, David G. Johnston wrote:

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.

pg_upgrade only dumps/restores the database schema, which is not
something most people would consider dump/restore; see:

https://momjian.us/main/writings/pgsql/pg_upgrade.pdf

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.

Yes, you are correct. It used to be under "modules" and we didn't
update this text, partly because this it not in our source git tree;
updated patch attached.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On Thu, Apr 4, 2024 at 2:23 PM Bruce Momjian <bruce@momjian.us> wrote:

-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).

Would be a shame to lose the EOL acronym.

+Such upgrades might require manual changes to complete so always read

+the release notes first.

Proposal:
"Such upgrades might require additional steps, so always read the release
notes first."

I went with frequently-encountered and low risk bugs".

But neither of those classifications are really true. Especially the "low
risk" part - I could see various ways a reader could wrongly interpret that.

Cheers,
Greg

On Thu, Apr 4, 2024 at 04:38:10PM -0400, Greg Sabino Mullane wrote:

On Thu, Apr 4, 2024 at 2:23 PM Bruce Momjian <bruce@momjian.us> wrote:
+Such upgrades might require manual changes to complete so always read
+the release notes first.

Proposal:
"Such upgrades might require additional steps, so always read the release notes
first."

Yes, I modified that sentence.

I went with frequently-encountered and low risk bugs".

But neither of those classifications are really true. Especially the "low risk"
part - I could see various ways a reader could wrongly interpret that.

I see your point. Updated patch attached.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On Thu, Apr 4, 2024 at 04:51:50PM -0400, Bruce Momjian wrote:

On Thu, Apr 4, 2024 at 04:38:10PM -0400, Greg Sabino Mullane wrote:

On Thu, Apr 4, 2024 at 2:23 PM Bruce Momjian <bruce@momjian.us> wrote:
+Such upgrades might require manual changes to complete so always read
+the release notes first.

Proposal:
"Such upgrades might require additional steps, so always read the release notes
first."

Yes, I modified that sentence.

I went with frequently-encountered and low risk bugs".

But neither of those classifications are really true. Especially the "low risk"
part - I could see various ways a reader could wrongly interpret that.

I see your point. Updated patch attached.

I am ready to apply this patch to the website. How do I do this? Do I
just commit this to the pgweb git tree? Does that push to the website?

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Only you can decide what is important to you.

On 4/12/24 2:12 PM, Bruce Momjian wrote:

I am ready to apply this patch to the website. How do I do this? Do I
just commit this to the pgweb git tree? Does that push to the website?

I pushed this to the website[1]https://www.postgresql.org/support/versioning/.

Thanks,

Jonathan

[1]: https://www.postgresql.org/support/versioning/