Re: New docs chapter on Transaction Management and related changes

On Tue, Nov 15, 2022 at 10:16:44AM +0000, Simon Riggs wrote:
> On Tue, 8 Nov 2022 at 03:41, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> >
> > On Mon, Nov 7, 2022 at 10:58:05AM +0000, Simon Riggs wrote:
> > > What I've posted is the merged patch, i.e. your latest patch, plus
> > > changes to RELEASE SAVEPOINT from you on Oct 16, plus changes based on
> > > the later comments from Robert and I.
> >
> > Thanks. I have two changes to your patch. First, I agree "destroy" is
> > the wrong word for this, but I don't think "subcommit" is good, for
> > three reasons:
> >
> > 1. Release merges the non-aborted changes into the previous transaction
> > _and_ frees their resources --- "subcommit" doesn't have both meanings,
> > which I think means if we need a single word, we should use "release"
> > and later define what that means.
> >
> > 2. The "subcommit" concept doesn't closely match the user-visible
> > behavior, even though we use subtransactions to accomplish this. Release
> > is more of a rollup/merge into the previously-active
> > transaction/savepoint.
> >
> > 3. "subcommit" is an implementation detail that I don't think we should
> > expose to users in the manual pages.
>
> I don't understand this - you seem to be presuming that "subcommit"
> means something different and then objecting to that difference.
>
> For me, "Subcommit" exactly matches what is happening because the code
> comments and details already use Subcommit in exactly this way.
>
> The main purpose of this patch is to talk about what is happening
> using the same language as we do in the code. The gap between the code
> and the docs isn't helping anyone.

I didn't think that was the purpose, and certainly not in the
reference/ref/man pages. I thought the purpose was to explain the
behavior clearly, and in the "Internals" section, the internal API we
expose to users. I didn't think matching the code was ever a goal --- I
thought that is what the README files are for.

--
Bruce Momjian <bruce(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

Indecision is a decision. Inaction is an action. Mark Batterson