Re: missing documentation for streaming in-progress transactions

On Wed, Apr 7, 2021 at 10:15 PM Amit Kapila <amit(dot)kapila16(at)gmail(dot)com> wrote:
>
> On Wed, Apr 7, 2021 at 1:11 PM Ajin Cherian <itsajin(at)gmail(dot)com> wrote:
> >
> > Hi,
> >
> > Found that some documentation hasn't been updated for the changes made as part of
> > streaming large in-progress transactions. Attached a patch that adds the missing changes. Let me know if anything more needs to be added or any comments on this change.
> >
>
> Thanks, this mostly looks good to me. I have slightly modified it.
> See, what do you think of the attached?
>

1.
I felt that this protocol documentation needs to include something
like a "Since: 2" notation (e.g. see how the javadoc API [1] does it)
otherwise with more message types and more protocol versions it is
quickly going to become too complicated to know what message or
message attribute belongs with what protocol.

2.
There are inconsistent terms used for a transaction id.
e.g.1 Sometimes called " Transaction id."
e.g.2 Sometimes called "Xid of the transaction"
I think there should be consistent terminology used on this page

3.
There is inconsistent wording for what seems to be the same condition.
e.g.1 The existing documentation [2] says "Xid of the transaction. The
XID is sent only when user has requested streaming of in-progress
transactions."
e.g.2 For a similar case the patch says "Xid of the transaction (only
present for streamed transactions)."
I think there should be consistent wording used on this page where possible.

------
[1] https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html
[2] https://www.postgresql.org/docs/devel/protocol-logicalrep-message-formats.html

Kind Regards,
Peter Smith.
Fujitsu Australia