Date: Wed, 30 Nov 2022 10:41:14 -0500
From: Bruce Momjian <bruce@momjian.us>
To: "David G. Johnston" <david.g.johnston@gmail.com>
Cc: Peter Eisentraut <peter.eisentraut@enterprisedb.com>,
	Laurenz Albe <laurenz.albe@cybertec.at>,
	Simon Riggs <simon.riggs@enterprisedb.com>,
	Robert Treat <rob@xzilla.net>,
	Alvaro Herrera <alvherre@alvh.no-ip.org>,
	Erik Rijkers <er@xs4all.nl>, Justin Pryzby <pryzby@telsasoft.com>,
	PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Subject: Re: New docs chapter on Transaction Management and related changes
Message-ID: <Y4d5mrYALQXOS0bI@momjian.us>
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>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: 
 <CAKFQuwZpfpq_JiMc0tXXew-5bAW2ZgFqHRNNhdSiWpporHi--Q@mail.gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/Y4d5mrYALQXOS0bI%40momjian.us>
Precedence: bulk

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.