Date: Fri, 18 Nov 2022 14:37:39 -0500
From: Bruce Momjian <bruce@momjian.us>
To: Simon Riggs <simon.riggs@enterprisedb.com>
Cc: Laurenz Albe <laurenz.albe@cybertec.at>, 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: <Y3ffA2+CfBTKNGkO@momjian.us>
References: <20221014084615.chvollxv3oz43oqu@alvherre.pgsql>
 <CANbhV-E287+hqhEbC7vCShT16LKYM8aUhrvxQZdjX2osKAETkQ@mail.gmail.com>
 <Y0m9tIrlMqaA9dwP@momjian.us>
 <CAJSLCQ32vZ8S+yFbO1bKbKT=JE8Q6oRJXeRqfN6Atk-XJKPr7g@mail.gmail.com>
 <Y0tZf7N+cUJ9ebPI@momjian.us>
 <80a5fd9c080d66e62f90c9565e3e1b54e61f584c.camel@cybertec.at>
 <Y2i3BDs9oNA4R/XP@momjian.us>
 <CANbhV-FVQK1Rsq+p2pY8FmZXhF0Vj5PuCrJdeFMTeFMmXNfcoQ@mail.gmail.com>
 <Y2nP04/3BHQOviVB@momjian.us>
 <CANbhV-HFpCXzPNOt2wwdvrcTwN9rBuONEH7GTOSdY=5PP_pSbw@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: 
 <CANbhV-HFpCXzPNOt2wwdvrcTwN9rBuONEH7GTOSdY=5PP_pSbw@mail.gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/Y3ffA2%2BCfBTKNGkO%40momjian.us>
Precedence: bulk

On Tue, Nov 15, 2022 at 10:16:44AM +0000, Simon Riggs wrote:
> On Tue, 8 Nov 2022 at 03:41, Bruce Momjian <bruce@momjian.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@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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