From: Bruce Momjian <bruce@momjian.us>
To: David G. Johnston <david.g.johnston@gmail.com>
Cc: Peter Eisentraut <peter.eisentraut@enterprisedb.com>
Cc: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: Simon Riggs <simon.riggs@enterprisedb.com>
Cc: Robert Treat <rob@xzilla.net>
Cc: Alvaro Herrera <alvherre@alvh.no-ip.org>
Cc: Erik Rijkers <er@xs4all.nl>
Cc: Justin Pryzby <pryzby@telsasoft.com>
Cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Subject: Re: New docs chapter on Transaction Management and related changes
Date: Wed, 30 Nov 2022 10:41:14 -0500
Message-ID: <Y4d5mrYALQXOS0bI@momjian.us> (raw)
In-Reply-To: <CAKFQuwZpfpq_JiMc0tXXew-5bAW2ZgFqHRNNhdSiWpporHi--Q@mail.gmail.com>
References: <80a5fd9c080d66e62f90c9565e3e1b54e61f584c.camel@cybertec.at>
<CANbhV-GafnnLmyMmjwYGFFcspk_twoEO56M3jiB7D0p_TkUmZA@mail.gmail.com>
<3603e6e85544daa5300c7106c31bc52673711cd0.camel@cybertec.at>
<Y3fY9nDysfSayXLJ@momjian.us>
<Y4a3I+sKKoXlylpt@momjian.us>
<c6304b19-6ff7-f3af-0148-cf7aa7e2fbfd@enterprisedb.com>
<Y4dgF4CeFUY35U2T@momjian.us>
<CAKFQuwZjMCjUkTB7+Cgy1bcu-c+teOPdNEMEn7FvhL_7WA5EcQ@mail.gmail.com>
<Y4dwnkU6XyHvT3hX@momjian.us>
<CAKFQuwZpfpq_JiMc0tXXew-5bAW2ZgFqHRNNhdSiWpporHi--Q@mail.gmail.com>
On Wed, Nov 30, 2022 at 08:25:19AM -0700, David G. Johnston wrote:
> On Wed, Nov 30, 2022 at 8:02 AM Bruce Momjian <bruce@momjian.us> wrote:
> On Wed, Nov 30, 2022 at 07:10:35AM -0700, David G. Johnston wrote:
> If everyone agrees this new chapter is helpful, and as helpful to PG 11
> users as PG 16 users, why would we not give users this information in
> our docs now? What is the downside? Chapter numbers? Translations?
>
> Admittedly the policy is more about "we don't expend any effort to write back
> branch patches for this kind of material" rather than "we don't do back
> patching because it causes problems". But it is an existing policy, applied
> consistently through the years, and treating the documentation like a book,
> even though it is published in a non-physical medium, is a reasonable guideline
> to follow.
Well, we have not backpatched cosmetic or wording improvements into back
branches, usually, though unclear wording has been backpatched because
the value is more significant than the disruption. I think we look at
doc backpatching on an individual basis, because there are limited
risks, unlike code changes.
> My desire to get it out in an official release early goes against this policy,
> and I'm fine waiting for v16 on that basis. The only reason I'm good with
> updating v15 is that I basically consider anything in the first 3 point
> releases of a major version to be a "delta" release.
Well, yeah, I think the PG 15-16 is kind of an odd approach, though I
can see the value of doing that since we could say anyone who cares
about these details should be on the most recent major release. I think
you are reinforcing my basic approach that doc changes can't have a
simple blanket policy, unlike code, because of the limited risks and
significan value.
> One back-patchable idea to consider would be adding a note at the top of the
> page(s) highlighting the fact that said material has been superseded by more
> current documentation, with a link. But the idea of changing long-released
> (see my delta comment above) material doesn't sit well with me or the policy.
Uh, I don't share that concern, as long as it is mentioned in the minor
release notes.
> I assume this new chapter would be mentioned in the minor release notes.
>
> We don't do release notes for documentation changes.
Uh, I certainly have done it for significant doc improvements in major
releases, so I don't see a problem in doing it for minor releases,
especially since this information has been needed in our docs for years.
What I am basically saying is that "we have always done it that way" is
an insufficient reason for me --- we should have some logic for _why_ we
have a policy, and I am not seeing that here.
This is obviously a bigger issue than this particular patch.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Embrace your flaws. They make you human, rather than perfect,
which you will never be.
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: bruce@momjian.us, david.g.johnston@gmail.com, peter.eisentraut@enterprisedb.com, laurenz.albe@cybertec.at, simon.riggs@enterprisedb.com, rob@xzilla.net, alvherre@alvh.no-ip.org, er@xs4all.nl, pryzby@telsasoft.com
Subject: Re: New docs chapter on Transaction Management and related changes
In-Reply-To: <Y4d5mrYALQXOS0bI@momjian.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox