Re: language cleanups in code and docs

Hi Andres,

Thanks for doing this!

On 6/15/20 2:22 PM, Andres Freund wrote:
>
> We've removed the use of "slave" from most of the repo (one use
> remained, included here), but we didn't do the same for master. In the
> attached series I replaced most of the uses.
>
> 0001: tap tests: s/master/primary/
> Pretty clear cut imo.

Nothing to argue with here as far as I can see. It's a lot of churn,
though, so the sooner it goes in the better so people can update for the
next CF.

> 0002: code: s/master/primary/
> This also includes a few minor other changes (s/in master/on the
> primary/, a few 'the's added). Perhaps it'd be better to do those
> separately?

I would only commit the grammar/language separately if the commit as a
whole does not go in. Some of them really do make the comments much
clearer beyond just in/on.

I think the user-facing messages, e.g.:

- errhint("Make sure the configuration parameter \"%s\" is set on the
master server.",
+ errhint("Make sure the configuration parameter \"%s\" is set on the
primary server.",

should go in no matter what so we are consistent with our documentation.
Same for the postgresql.conf updates.

> 0003: code: s/master/leader/
> This feels pretty obvious. We've largely used the leader / worker
> terminology, but there were a few uses of master left.

Yeah, leader already outnumbers master by a lot. Looks good.

> 0004: code: s/master/$other/
> This is most of the remaining uses of master in code. A number of
> references to 'master' in the context of toast, a few uses of 'master
> copy'. I guess some of these are a bit less clear cut.

Not sure I love authoritative, e.g.

+ * fullPageWrites is the authoritative value used by all backends to

and

+ * grabbed a WAL insertion lock to read the authoritative value in

Possibly "shared"?

+ * Create the Tcl interpreter subsidiary to pltcl_hold_interp.

Maybe use "worker" here? Not much we can do about the Tcl function name,
though. It's pretty localized, though, so may not matter much.

> 0005: docs: s/master/primary/
> These seem mostly pretty straightforward to me. The changes in
> high-availability.sgml probably deserve the most attention.

+ on primary and the current time on the standby. Delays in transfer

on *the* primary

I saw a few places where readability could be improved, but this patch
did not make any of them worse, and did make a few better.

> 0006: docs: s/master/root/
> Here using root seems a lot better than master anyway (master seems
> confusing in regard to inheritance scenarios). But perhaps parent
> would be better? Went with root since it's about the topmost table.

I looked through to see if there was an instance of parent that should
be changed to root but I didn't see any. Even if there are, it's no
worse than before.

> 0007: docs: s/master/supervisor/
> I guess this could be a bit more contentious. Supervisor seems clearer
> to me, but I can see why people would disagree. See also later point
> about changes I have not done at this stage.

Supervisor seems OK to me, but the postmaster has a special place since
there is only one of them. Main supervisor, root supervisor?

> 0008: docs: WIP multi-master rephrasing.
> I like neither the new nor the old language much. I'd welcome input.

Why not multi-primary?

> After this series there are only two widespread use of 'master' in the
> tree.
> 1) 'postmaster'. As changing that would be somewhat invasive, the word
> is a bit more ambiguous, and it's largely just internal, I've left
> this alone for now. I personally would rather see this renamed as
> supervisor, which'd imo actually would also be a lot more
> descriptive. I'm willing to do the work, but only if there's at least
> some agreement.

FWIW, I don't consider this to be a very big change from an end-user
perspective. I don't think the majority of users interact directly with
the postmaster, rather they are using systemd, pg_ctl, pg_ctlcluster, etc.

As for postmaster.pid and postmaster.opts, we have renamed plenty of
things in the past so this is just one more. They'd be better and
clearer as postgresql.pid and postgresql.opts, IMO.

Overall I'm +.5 because I may just be ignorant of the pain this will cause.

> 2) 'master' as a reference to the branch. Personally I be in favor of
> changing the branch name, but it seems like it'd be better done as a
> somewhat separate discussion to me, as it affects development
> practices to some degree.

Happily this has no end-user impact. I think "main" is a good
alternative but I agree this feels like a separate topic.

One last thing -- are we considering back-patching any/all of this?

Regards,
--
-David
david(at)pgmasters(dot)net