Re: New docs chapter on Transaction Management and related changes

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(at)momjian(dot)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(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

Embrace your flaws. They make you human, rather than perfect,
which you will never be.