Обсуждение: Reports on obsolete Postgres versions

I am seeing an increasing number of bug/problem reports on obsolete
Postgres versions, either not running a superseded minor version, or
running an unsupported major version.

What can we do to reduce such reports, or at least give a consistent
response?  It is very helpful that we have this web page, and I have
made a habit of pointing reporters to that page since it has all the
information they need:

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

-- 
  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 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 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”
asthe 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
bitsmaller 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
bitsmaller 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 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 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 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 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].

Thanks,

Jonathan

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