Thread: language cleanups in code and docs

language cleanups in code and docs

From
Andres Freund
Date:
Hi,

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.

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?

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.

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.

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

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.

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.

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


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.
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.

Greetings,

Andres Freund

Attachment

Re: language cleanups in code and docs

From
Daniel Gustafsson
Date:
> On 15 Jun 2020, at 20:22, Andres Freund <andres@anarazel.de> wrote:

Thanks for picking this up!

> 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've never really liked the name postmaster as I don't think it conveys
meaning.  I support renaming to supervisor or a similar term.

cheers ./daniel



Re: language cleanups in code and docs

From
Thomas Munro
Date:
On Tue, Jun 16, 2020 at 7:04 AM Daniel Gustafsson <daniel@yesql.se> wrote:
> > On 15 Jun 2020, at 20:22, Andres Freund <andres@anarazel.de> wrote:
>
> Thanks for picking this up!
>
> > 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've never really liked the name postmaster as I don't think it conveys
> meaning.  I support renaming to supervisor or a similar term.

+1.  Postmaster has always sounded like a mailer daemon or something,
which we ain't.



Re: language cleanups in code and docs

From
Bruce Momjian
Date:
On Tue, Jun 16, 2020 at 09:53:34AM +1200, Thomas Munro wrote:
> On Tue, Jun 16, 2020 at 7:04 AM Daniel Gustafsson <daniel@yesql.se> wrote:
> > > On 15 Jun 2020, at 20:22, Andres Freund <andres@anarazel.de> wrote:
> >
> > Thanks for picking this up!
> >
> > > 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've never really liked the name postmaster as I don't think it conveys
> > meaning.  I support renaming to supervisor or a similar term.
> 
> +1.  Postmaster has always sounded like a mailer daemon or something,
> which we ain't.

Postmaster is historically confused with the postmaster email account:

    https://en.wikipedia.org/wiki/Postmaster_(computing)

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee




Re: language cleanups in code and docs

From
Tom Lane
Date:
Daniel Gustafsson <daniel@yesql.se> writes:
> On 15 Jun 2020, at 20:22, Andres Freund <andres@anarazel.de> wrote:
>> 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've never really liked the name postmaster as I don't think it conveys
> meaning.  I support renaming to supervisor or a similar term.

Meh.  That's carrying PC naming foibles to the point where they
negatively affect our users (by breaking start scripts and such).
I think we should leave this alone.

            regards, tom lane



Re: language cleanups in code and docs

From
Andres Freund
Date:
Hi,

On 2020-06-15 19:54:25 -0400, Tom Lane wrote:
> Daniel Gustafsson <daniel@yesql.se> writes:
> > On 15 Jun 2020, at 20:22, Andres Freund <andres@anarazel.de> wrote:
> >> 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've never really liked the name postmaster as I don't think it conveys
> > meaning.  I support renaming to supervisor or a similar term.
>
> Meh.  That's carrying PC naming foibles to the point where they
> negatively affect our users (by breaking start scripts and such).
> I think we should leave this alone.

postmaster is just a symlink, which we very well could just leave in
place... I was really just thinking of the code level stuff. And I think
there's some clarity reasons to rename it as well (see comments by
others in the thread).

Anyway, for now my focus is on patches in the series...

- Andres



Re: language cleanups in code and docs

From
Peter Geoghegan
Date:
On Mon, Jun 15, 2020 at 4:54 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Meh.  That's carrying PC naming foibles to the point where they
> negatively affect our users (by breaking start scripts and such).
> I think we should leave this alone.

+1. Apart from the practical considerations, I just don't see a
problem with the word postmaster. My mother is a postmistress.

I'm in favor of updating any individual instances of the word "master"
to the preferred equivalent in code and code comments, though.

-- 
Peter Geoghegan



Re: language cleanups in code and docs

From
Magnus Hagander
Date:


On Tue, Jun 16, 2020 at 2:23 AM Andres Freund <andres@anarazel.de> wrote:
Hi,

On 2020-06-15 19:54:25 -0400, Tom Lane wrote:
> Daniel Gustafsson <daniel@yesql.se> writes:
> > On 15 Jun 2020, at 20:22, Andres Freund <andres@anarazel.de> wrote:
> >> 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've never really liked the name postmaster as I don't think it conveys
> > meaning.  I support renaming to supervisor or a similar term.
>
> Meh.  That's carrying PC naming foibles to the point where they
> negatively affect our users (by breaking start scripts and such).
> I think we should leave this alone.

postmaster is just a symlink, which we very well could just leave in
place... I was really just thinking of the code level stuff. And I think
there's some clarity reasons to rename it as well (see comments by
others in the thread).


Is the symlink even used? If not we could just get rid of it. 

I'd be more worried about for example postmaster.pid, which would break a *lot* of scripts and integrations. postmaster is also exposed in the system catalogs.


--

Re: language cleanups in code and docs

From
Joe Conway
Date:
On 6/16/20 3:26 AM, Magnus Hagander wrote:
> On Tue, Jun 16, 2020 at 2:23 AM Andres Freund wrote:
>     postmaster is just a symlink, which we very well could just leave in
>     place... I was really just thinking of the code level stuff. And I think
>     there's some clarity reasons to rename it as well (see comments by
>     others in the thread).
>
> Is the symlink even used? If not we could just get rid of it. 


I am pretty sure that last time I checked Devrim was still using it in his
systemd unit file bundled with the PGDG rpms, although that was probably a
couple of years ago.

Joe
--
Crunchy Data - http://crunchydata.com
PostgreSQL Support for Secure Enterprises
Consulting, Training, & Open Source Development


Attachment

Re: language cleanups in code and docs

From
Andrew Dunstan
Date:
On 6/16/20 9:10 AM, Joe Conway wrote:
> On 6/16/20 3:26 AM, Magnus Hagander wrote:
>> On Tue, Jun 16, 2020 at 2:23 AM Andres Freund wrote:
>>     postmaster is just a symlink, which we very well could just leave in
>>     place... I was really just thinking of the code level stuff. And I think
>>     there's some clarity reasons to rename it as well (see comments by
>>     others in the thread).
>>
>> Is the symlink even used? If not we could just get rid of it. 
>
> I am pretty sure that last time I checked Devrim was still using it in his
> systemd unit file bundled with the PGDG rpms, although that was probably a
> couple of years ago.
>


Just checked a recent install and it's there.


Honestly, I think I'm with Tom, and we can just let this one alone.


cheers


andrew


-- 
Andrew Dunstan                https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services




Re: language cleanups in code and docs

From
Tom Lane
Date:
Magnus Hagander <magnus@hagander.net> writes:
> I'd be more worried about for example postmaster.pid, which would break a
> *lot* of scripts and integrations. postmaster is also exposed in the system
> catalogs.

Oooh, that's an excellent point.  A lot of random stuff knows that file
name.

To be clear, I'm not against removing incidental uses of the word
"master".  But the specific case of "postmaster" seems a little too
far ingrained to be worth changing.

            regards, tom lane



Re: language cleanups in code and docs

From
Bruce Momjian
Date:
On Mon, Jun 15, 2020 at 11:22:35AM -0700, Andres Freund wrote:
> 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.

Because we allow multiple levels of inheritance, I have always wanted a
clear term for the top-most parent.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee




Re: language cleanups in code and docs

From
David Steele
Date:
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@pgmasters.net



Re: language cleanups in code and docs

From
Andres Freund
Date:
Hi,

On 2020-06-16 17:14:57 -0400, David Steele wrote:
> 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.

Yea, unless somebody protests I'm planning to push this part soon.


> > 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"?

I don't think shared is necessarily correct for all of these. E.g. in
the GetRedoRecPtr() there's two shared values at play, but only one is
"authoritative".


> +     * 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.

I don't think it matters much what we use here


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

My understanding of primary is that there really can't be two things
that are primary in relation to each other. active/active is probably
the most common term in use besides multi-master.


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

I don't think there's a good reason to do so.

Thanks for the look!

Greetings,

Andres Freund



Re: language cleanups in code and docs

From
David Steele
Date:
On 6/16/20 6:27 PM, Andres Freund wrote:
> On 2020-06-16 17:14:57 -0400, David Steele wrote:
>> On 6/15/20 2:22 PM, Andres Freund wrote:
> 
>>> 0008: docs: WIP multi-master rephrasing.
>>>     I like neither the new nor the old language much. I'd welcome input.
>>
>> Why not multi-primary?
> 
> My understanding of primary is that there really can't be two things
> that are primary in relation to each other. 

Well, I think the same is true for multi-master and that's pretty common.

> active/active is probably
> the most common term in use besides multi-master.

Works for me and can always be updated later if we come up with 
something better. At least active-active will be easier to search for.

>> One last thing -- are we considering back-patching any/all of this?
> 
> I don't think there's a good reason to do so.

I was thinking of back-patching pain but if you don't think that's an 
issue then I'm not worried about it.

> Thanks for the look!

You are welcome!

-- 
-David
david@pgmasters.net



Re: language cleanups in code and docs

From
Andrew Dunstan
Date:
On 6/15/20 2:22 PM, Andres Freund wrote:
> 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.
>


I'm OK with this, but I would need plenty of notice to get the buildfarm
adjusted.


cheers


andrew


-- 
Andrew Dunstan                https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services




Re: language cleanups in code and docs

From
Tom Lane
Date:
Andrew Dunstan <andrew.dunstan@2ndquadrant.com> writes:
> On 6/15/20 2:22 PM, Andres Freund wrote:
>> 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.

> I'm OK with this, but I would need plenty of notice to get the buildfarm
> adjusted.

"master" is the default branch name established by git, is it not?  Not
something we picked.  I don't feel like we need to be out front of the
rest of the world in changing that.  It'd be a cheaper change than some of
the other proposals in this thread, no doubt, but it would still create
confusion for new hackers who are used to the standard git convention.

            regards, tom lane



Re: language cleanups in code and docs

From
Dave Cramer
Date:


On Tue, 16 Jun 2020 at 19:55, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Andrew Dunstan <andrew.dunstan@2ndquadrant.com> writes:
> On 6/15/20 2:22 PM, Andres Freund wrote:
>> 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.

> I'm OK with this, but I would need plenty of notice to get the buildfarm
> adjusted.

"master" is the default branch name established by git, is it not?  Not
something we picked.  I don't feel like we need to be out front of the
rest of the world in changing that.  It'd be a cheaper change than some of
the other proposals in this thread, no doubt, but it would still create
confusion for new hackers who are used to the standard git convention.

While it is the default I expect that will change soon. Github is planning on making main the default. https://www.zdnet.com/article/github-to-replace-master-with-alternative-term-to-avoid-slavery-references/

Many projects are moving from master to main.

I expect it will be less confusing than you think.

Dave Cramer
www.postgres.rocks

Re: language cleanups in code and docs

From
Alvaro Herrera
Date:
On 2020-Jun-16, Tom Lane wrote:

> Andrew Dunstan <andrew.dunstan@2ndquadrant.com> writes:
> > On 6/15/20 2:22 PM, Andres Freund wrote:
> >> 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.
> 
> > I'm OK with this, but I would need plenty of notice to get the buildfarm
> > adjusted.
> 
> "master" is the default branch name established by git, is it not?  Not
> something we picked.  I don't feel like we need to be out front of the
> rest of the world in changing that.  It'd be a cheaper change than some of
> the other proposals in this thread, no doubt, but it would still create
> confusion for new hackers who are used to the standard git convention.

Git itself is discussing this:
https://public-inbox.org/git/41438A0F-50E4-4E58-A3A7-3DAAECB5576B@jramsay.com.au/T/#t
and it seems that "main" is the winning choice.

(Personally) I would leave master to have root, would leave root to have
default, would leave default to have primary, would leave primary to
have base, would leave base to have main, would leave main to have
mainline.

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services



Re: language cleanups in code and docs

From
Tom Lane
Date:
Alvaro Herrera <alvherre@2ndquadrant.com> writes:
> On 2020-Jun-16, Tom Lane wrote:
>> "master" is the default branch name established by git, is it not?  Not
>> something we picked.

> Git itself is discussing this:
> https://public-inbox.org/git/41438A0F-50E4-4E58-A3A7-3DAAECB5576B@jramsay.com.au/T/#t
> and it seems that "main" is the winning choice.

Oh, interesting.  If they do change I'd be happy to follow suit.
But let's wait and see what they do, rather than possibly ending
up with our own private convention.

            regards, tom lane



Re: language cleanups in code and docs

From
Magnus Hagander
Date:


On Wed, Jun 17, 2020 at 3:44 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
Alvaro Herrera <alvherre@2ndquadrant.com> writes:
> On 2020-Jun-16, Tom Lane wrote:
>> "master" is the default branch name established by git, is it not?  Not
>> something we picked.

> Git itself is discussing this:
> https://public-inbox.org/git/41438A0F-50E4-4E58-A3A7-3DAAECB5576B@jramsay.com.au/T/#t
> and it seems that "main" is the winning choice.

Oh, interesting.  If they do change I'd be happy to follow suit.
But let's wait and see what they do, rather than possibly ending
up with our own private convention.

I'm +1 for changing it (with good warning time to handle the buildfarm situation), but also very much +1 for waiting to see exactly what upstream (git) decides on and make sure we change to the same.  The worst possible combination would be that we change it to something that's *different* than upstream ends up with (even if upstream ends up being configurable).

--

Re: language cleanups in code and docs

From
Laurenz Albe
Date:
On Tue, 2020-06-16 at 19:55 -0400, Tom Lane wrote:
> Andrew Dunstan <andrew.dunstan@2ndquadrant.com> writes:
> > On 6/15/20 2:22 PM, Andres Freund wrote:
> > > 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.
> > I'm OK with this, but I would need plenty of notice to get the buildfarm
> > adjusted.
> 
> "master" is the default branch name established by git, is it not?  Not
> something we picked.  I don't feel like we need to be out front of the
> rest of the world in changing that.  It'd be a cheaper change than some of
> the other proposals in this thread, no doubt, but it would still create
> confusion for new hackers who are used to the standard git convention.

I have the feeling that all this is going somewhat too far.

I feel fine with removing the term "slave", even though I have no qualms
about enslaving machines.

But the term "master" is not restricted to slavery.  It can just as well
imply expert knowledge (think academic degree), and it can denote someone
with the authority to command (there is nothing wrong with "servant", right?
Or do we have to abolish the term "server" too?).

I appreciate that other people's sensitivities might be different, and I
don't want to start a fight over it.  But renaming things makes the code
history harder to read, so it should be used with moderation.

Yours,
Laurenz Albe




Re: language cleanups in code and docs

From
Magnus Hagander
Date:


On Mon, Jun 15, 2020 at 8:23 PM Andres Freund <andres@anarazel.de> wrote:
Hi,

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.

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?

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.

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.

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

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.

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.

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


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.
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.


In looking at this I realize we also have exactly one thing referred to as "blacklist" in our codebase, which is the "enum blacklist" (and then a small internal variable in pgindent). AFAICT, it's not actually exposed to userspace anywhere, so we could probably make the attached change to blocklist at no "cost" (the only thing changed is the name of the hash table, and we definitely change things like that in normal releases with no specific thought on backwards compat).

//Magnus 
Attachment

Re: language cleanups in code and docs

From
"Jonathan S. Katz"
Date:
On 6/17/20 6:32 AM, Magnus Hagander wrote:

> In looking at this I realize we also have exactly one thing referred to
> as "blacklist" in our codebase, which is the "enum blacklist" (and then
> a small internal variable in pgindent). AFAICT, it's not actually
> exposed to userspace anywhere, so we could probably make the attached
> change to blocklist at no "cost" (the only thing changed is the name of
> the hash table, and we definitely change things like that in normal
> releases with no specific thought on backwards compat).

+1. Though if we are doing that, we should also handle "whitelist" too,
as this attached patch does. It's mostly in comments (with one Perl
variable), but I switched the language around to use "allowed"

Jonathan

Attachment

Re: language cleanups in code and docs

From
"Jonathan S. Katz"
Date:
On 6/17/20 6:06 AM, Laurenz Albe wrote:
> On Tue, 2020-06-16 at 19:55 -0400, Tom Lane wrote:
>> Andrew Dunstan <andrew.dunstan@2ndquadrant.com> writes:
>>> On 6/15/20 2:22 PM, Andres Freund wrote:
>>>> 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.
>>> I'm OK with this, but I would need plenty of notice to get the buildfarm
>>> adjusted.
>>
>> "master" is the default branch name established by git, is it not?  Not
>> something we picked.  I don't feel like we need to be out front of the
>> rest of the world in changing that.  It'd be a cheaper change than some of
>> the other proposals in this thread, no doubt, but it would still create
>> confusion for new hackers who are used to the standard git convention.
>
> I have the feeling that all this is going somewhat too far.

First, I +1 the changes Andres proposed overall. In addition to it being
the right thing to do, it brings inline a lot of the terminology we have
been using to describe concepts in PostgreSQL for years (e.g.
primary/replica).

For the name of the git branch, I +1 following the convention of the git
upstream, and make changes based on that. Understandably, it could break
things for a bit, but that will occur for a lot of other projects as
well and everyone will adopt. We have the benefit that we're just
beginning our new development cycle too, so this is a good time to
introduce breaking change ;)

Jonathan


Attachment

Re: language cleanups in code and docs

From
Andrew Dunstan
Date:
On 6/17/20 6:32 AM, Magnus Hagander wrote:
>
>
>
>
>
> In looking at this I realize we also have exactly one thing referred
> to as "blacklist" in our codebase, which is the "enum blacklist" (and
> then a small internal variable in pgindent). AFAICT, it's not actually
> exposed to userspace anywhere, so we could probably make the attached
> change to blocklist at no "cost" (the only thing changed is the name
> of the hash table, and we definitely change things like that in normal
> releases with no specific thought on backwards compat).
>
>

I'm not sure I like doing s/Black/Block/ here. It reads oddly. There are
too many other uses of Block in the sources. Forbidden might be a better
substitution, or Banned maybe. BanList is even less characters than
BlackList.


I know, bikeshedding here.


cheers


andrew



-- 
Andrew Dunstan                https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services




Re: language cleanups in code and docs

From
Tom Lane
Date:
Andrew Dunstan <andrew.dunstan@2ndquadrant.com> writes:
> On 6/17/20 6:32 AM, Magnus Hagander wrote:
>> In looking at this I realize we also have exactly one thing referred
>> to as "blacklist" in our codebase, which is the "enum blacklist" (and
>> then a small internal variable in pgindent). AFAICT, it's not actually
>> exposed to userspace anywhere, so we could probably make the attached
>> change to blocklist at no "cost" (the only thing changed is the name
>> of the hash table, and we definitely change things like that in normal
>> releases with no specific thought on backwards compat).

> I'm not sure I like doing s/Black/Block/ here. It reads oddly. There are
> too many other uses of Block in the sources. Forbidden might be a better
> substitution, or Banned maybe. BanList is even less characters than
> BlackList.

I think worrying about blacklist/whitelist is carrying things a bit far
in the first place.

            regards, tom lane



Re: language cleanups in code and docs

From
Andrew Dunstan
Date:
On 6/17/20 11:00 AM, Tom Lane wrote:
> Andrew Dunstan <andrew.dunstan@2ndquadrant.com> writes:
>> On 6/17/20 6:32 AM, Magnus Hagander wrote:
>>> In looking at this I realize we also have exactly one thing referred
>>> to as "blacklist" in our codebase, which is the "enum blacklist" (and
>>> then a small internal variable in pgindent). AFAICT, it's not actually
>>> exposed to userspace anywhere, so we could probably make the attached
>>> change to blocklist at no "cost" (the only thing changed is the name
>>> of the hash table, and we definitely change things like that in normal
>>> releases with no specific thought on backwards compat).
>> I'm not sure I like doing s/Black/Block/ here. It reads oddly. There are
>> too many other uses of Block in the sources. Forbidden might be a better
>> substitution, or Banned maybe. BanList is even less characters than
>> BlackList.
> I think worrying about blacklist/whitelist is carrying things a bit far
> in the first place.


For the small effort and minimal impact involved, I think it's worth
avoiding the bad publicity.


cheers


andrew


-- 
Andrew Dunstan                https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services




Re: language cleanups in code and docs

From
Magnus Hagander
Date:


On Wed, Jun 17, 2020 at 4:15 PM Andrew Dunstan <andrew.dunstan@2ndquadrant.com> wrote:

On 6/17/20 6:32 AM, Magnus Hagander wrote:
>
>
>
>
>
> In looking at this I realize we also have exactly one thing referred
> to as "blacklist" in our codebase, which is the "enum blacklist" (and
> then a small internal variable in pgindent). AFAICT, it's not actually
> exposed to userspace anywhere, so we could probably make the attached
> change to blocklist at no "cost" (the only thing changed is the name
> of the hash table, and we definitely change things like that in normal
> releases with no specific thought on backwards compat).
>
>

I'm not sure I like doing s/Black/Block/ here. It reads oddly. There are
too many other uses of Block in the sources. Forbidden might be a better
substitution, or Banned maybe. BanList is even less characters than
BlackList.


I know, bikeshedding here.

I'd be OK with either of those really -- I went with block because it was the easiest one :)

Not sure the number of characters is the important part :) Banlist does make sense to me for other reasons though -- it's what it is, isn't it? It bans those oids from being used in the current session -- I don't think there's any struggle to "make that sentence work", which means that seems like the relevant term.

I do think it's worth doing -- it's a small round of changes, and it doesn't change anything user-exposed, so the cost for us is basically zero. 

--

Re: language cleanups in code and docs

From
"Jonathan S. Katz"
Date:
On 6/17/20 12:08 PM, Magnus Hagander wrote:
>
>
> On Wed, Jun 17, 2020 at 4:15 PM Andrew Dunstan
> <andrew.dunstan@2ndquadrant.com <mailto:andrew.dunstan@2ndquadrant.com>>
> wrote:
>
>
>     On 6/17/20 6:32 AM, Magnus Hagander wrote:
>     >
>     >
>     >
>     >
>     >
>     > In looking at this I realize we also have exactly one thing referred
>     > to as "blacklist" in our codebase, which is the "enum blacklist" (and
>     > then a small internal variable in pgindent). AFAICT, it's not actually
>     > exposed to userspace anywhere, so we could probably make the attached
>     > change to blocklist at no "cost" (the only thing changed is the name
>     > of the hash table, and we definitely change things like that in normal
>     > releases with no specific thought on backwards compat).
>     >
>     >
>
>     I'm not sure I like doing s/Black/Block/ here. It reads oddly. There are
>     too many other uses of Block in the sources. Forbidden might be a better
>     substitution, or Banned maybe. BanList is even less characters than
>     BlackList.
>
>
>     I know, bikeshedding here.
>
>
> I'd be OK with either of those really -- I went with block because it
> was the easiest one :)
>
> Not sure the number of characters is the important part :) Banlist does
> make sense to me for other reasons though -- it's what it is, isn't it?
> It bans those oids from being used in the current session -- I don't
> think there's any struggle to "make that sentence work", which means
> that seems like the relevant term.
>
> I do think it's worth doing -- it's a small round of changes, and it
> doesn't change anything user-exposed, so the cost for us is basically zero.

+1. I know post efforts for us to update our language have been
well-received, even long after the fact, and given this set has been
voiced actively and other fora and, as Magnus states, the cost for us to
change it is basically zero, we should just do it.

Jonathan


Attachment

Re: language cleanups in code and docs

From
David Steele
Date:
On 6/17/20 12:08 PM, Magnus Hagander wrote:
> On Wed, Jun 17, 2020 at 4:15 PM Andrew Dunstan 
> <andrew.dunstan@2ndquadrant.com <mailto:andrew.dunstan@2ndquadrant.com>> 
> 
>     I'm not sure I like doing s/Black/Block/ here. It reads oddly. There are
>     too many other uses of Block in the sources. Forbidden might be a better
>     substitution, or Banned maybe. BanList is even less characters than
>     BlackList.
> 
> I'd be OK with either of those really -- I went with block because it 
> was the easiest one :)
> 
> Not sure the number of characters is the important part :) Banlist does 
> make sense to me for other reasons though -- it's what it is, isn't it? 
> It bans those oids from being used in the current session -- I don't 
> think there's any struggle to "make that sentence work", which means 
> that seems like the relevant term.

I've seen also seen allowList/denyList as an alternative. I do agree 
that blockList is a bit confusing since we often use block in a very 
different context.

> I do think it's worth doing -- it's a small round of changes, and it 
> doesn't change anything user-exposed, so the cost for us is basically zero.

+1

Regards,
-- 
-David
david@pgmasters.net



Re: language cleanups in code and docs

From
Robert Haas
Date:
On Mon, Jun 15, 2020 at 2:23 PM Andres Freund <andres@anarazel.de> wrote:
> 0002: code: s/master/primary/
> 0003: code: s/master/leader/
> 0006: docs: s/master/root/
> 0007: docs: s/master/supervisor/

I'd just like to make the pointer here that there's value in trying to
use different terminology for different things. I picked "leader" and
"worker" for parallel query and tried to use them consistently because
"master" and "slave" were being used widely to refer to physical
replication, and I thought it would be clearer to use something
different, so I did. It's confusing if we use the same word for the
server from which others replicate, the table from which others
inherit, the process which initiates parallelism, and the first
process that is launched across the whole cluster, regardless of
*which* word we use for those things. So, I think there is every
possibility that with careful thought, we can actually make things
clearer, in addition to avoiding the use of terms that are no longer
welcome.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company



Re: language cleanups in code and docs

From
Tom Lane
Date:
Robert Haas <robertmhaas@gmail.com> writes:
> On Mon, Jun 15, 2020 at 2:23 PM Andres Freund <andres@anarazel.de> wrote:
>> 0002: code: s/master/primary/
>> 0003: code: s/master/leader/
>> 0006: docs: s/master/root/
>> 0007: docs: s/master/supervisor/

> I'd just like to make the pointer here that there's value in trying to
> use different terminology for different things.

+1 for that.

            regards, tom lane



Re: language cleanups in code and docs

From
Andres Freund
Date:
Hi,

On 2020-06-17 13:59:26 -0400, Robert Haas wrote:
> On Mon, Jun 15, 2020 at 2:23 PM Andres Freund <andres@anarazel.de> wrote:
> > 0002: code: s/master/primary/
> > 0003: code: s/master/leader/
> > 0006: docs: s/master/root/
> > 0007: docs: s/master/supervisor/
> 
> I'd just like to make the pointer here that there's value in trying to
> use different terminology for different things. I picked "leader" and
> "worker" for parallel query and tried to use them consistently because
> "master" and "slave" were being used widely to refer to physical
> replication, and I thought it would be clearer to use something
> different, so I did.

Just to be clear, that's exactly what I tried to do in the above
patches. E.g. in 0003 I tried to follow the scheme you just
outlined. There's a part of that patch that addresses pg_dump, but most
of the rest is just parallelism related pieces that ended up using
master, even though leader is the more widely used term.  I assume you
were just saying that the above use of different terms is actually
helpful:

> It's confusing if we use the same word for the server from which
> others replicate, the table from which others inherit, the process
> which initiates parallelism, and the first process that is launched
> across the whole cluster, regardless of *which* word we use for those
> things. So, I think there is every possibility that with careful
> thought, we can actually make things clearer, in addition to avoiding
> the use of terms that are no longer welcome.

With which I wholeheartedly agree.

Greetings,

Andres Freund



Re: language cleanups in code and docs

From
Bruce Momjian
Date:
On Wed, Jun 17, 2020 at 01:59:26PM -0400, Robert Haas wrote:
> On Mon, Jun 15, 2020 at 2:23 PM Andres Freund <andres@anarazel.de> wrote:
> > 0002: code: s/master/primary/
> > 0003: code: s/master/leader/
> > 0006: docs: s/master/root/
> > 0007: docs: s/master/supervisor/
> 
> I'd just like to make the pointer here that there's value in trying to
> use different terminology for different things. I picked "leader" and
> "worker" for parallel query and tried to use them consistently because
> "master" and "slave" were being used widely to refer to physical
> replication, and I thought it would be clearer to use something
> different, so I did. It's confusing if we use the same word for the
> server from which others replicate, the table from which others
> inherit, the process which initiates parallelism, and the first
> process that is launched across the whole cluster, regardless of
> *which* word we use for those things. So, I think there is every
> possibility that with careful thought, we can actually make things
> clearer, in addition to avoiding the use of terms that are no longer
> welcome.

I think the question is whether we can improve our terms as part of this
rewording, or if we make them worse.  When we got rid of slave and made
it standby, I think we made things worse since many of the replicas were
not functioning for the purpose of standby.  Standby is a role, not a
status, while replica is a status.

The other issue is how the terms interlink with other terms.  When we
used master/slave, multi-master matched the wording, but replication
didn't match.  If we go with replica, replication works, and
primary/replica kind of fits, e.g., master/replica does not.
Multi-master then no longer fits, multi-primary sounds odd, and
active-active doesn't match, though active-active is not used as much as
primary/replica, so maybe that is OK.  Ideally we would have all terms
matching, but maybe that is impossible.

My point is that these terms are symbolic (similes) --- the new terms
should link to their roles and to other terms in a logical way.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee




Re: language cleanups in code and docs

From
Andres Freund
Date:
Hi,

I've pushed most of the changes.

On 2020-06-16 18:59:25 -0400, David Steele wrote:
> On 6/16/20 6:27 PM, Andres Freund wrote:
> > On 2020-06-16 17:14:57 -0400, David Steele wrote:
> > > On 6/15/20 2:22 PM, Andres Freund wrote:
> > 
> > > > 0008: docs: WIP multi-master rephrasing.
> > > >     I like neither the new nor the old language much. I'd welcome input.
> > > 
> > > Why not multi-primary?
> > 
> > My understanding of primary is that there really can't be two things
> > that are primary in relation to each other.
> 
> Well, I think the same is true for multi-master and that's pretty common.
> 
> > active/active is probably
> > the most common term in use besides multi-master.
> 
> Works for me and can always be updated later if we come up with something
> better. At least active-active will be easier to search for.

What do you think about the attached?

Greetings,

Andres Freund

Attachment

Re: language cleanups in code and docs

From
David Steele
Date:
On 7/8/20 4:39 PM, Andres Freund wrote:
> Hi,
> 
> I've pushed most of the changes.
> 
> On 2020-06-16 18:59:25 -0400, David Steele wrote:
>> On 6/16/20 6:27 PM, Andres Freund wrote:
>>> On 2020-06-16 17:14:57 -0400, David Steele wrote:
>>>> On 6/15/20 2:22 PM, Andres Freund wrote:
>>>
>>>>> 0008: docs: WIP multi-master rephrasing.
>>>>>      I like neither the new nor the old language much. I'd welcome input.
>>>>
>>>> Why not multi-primary?
>>>
>>> My understanding of primary is that there really can't be two things
>>> that are primary in relation to each other.
>>
>> Well, I think the same is true for multi-master and that's pretty common.
>>
>>> active/active is probably
>>> the most common term in use besides multi-master.
>>
>> Works for me and can always be updated later if we come up with something
>> better. At least active-active will be easier to search for.
> 
> What do you think about the attached?

I think this phrasing in the original/updated version is pretty awkward:

+  A standby server that cannot be connected to until it is promoted to a
+  primary server is called a ...

How about:

+ A standby server that must be promoted to a primary server before
+ accepting connections is called a ...

Other than that it looks good to me.

Regards,
-- 
-David
david@pgmasters.net



Re: language cleanups in code and docs

From
Alvaro Herrera
Date:
On 2020-Jul-08, David Steele wrote:

> On 7/8/20 4:39 PM, Andres Freund wrote:

> I think this phrasing in the original/updated version is pretty awkward:
> 
> +  A standby server that cannot be connected to until it is promoted to a
> +  primary server is called a ...

Yeah.

> How about:
> 
> + A standby server that must be promoted to a primary server before
> + accepting connections is called a ...

How about just reducing it to "A standby server that doesn't accept
connection is called a ..."?  We don't really need to explain that if
you do promote the standby it will start accept connections -- do we?
It should be pretty obvious if you promote a standby, it will cease to
be a standby in the first place.  This verbiage seems excessive.

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services



Re: language cleanups in code and docs

From
David Steele
Date:
On 7/8/20 5:17 PM, Alvaro Herrera wrote:
> On 2020-Jul-08, David Steele wrote:
> 
>> On 7/8/20 4:39 PM, Andres Freund wrote:
> 
>> I think this phrasing in the original/updated version is pretty awkward:
>>
>> +  A standby server that cannot be connected to until it is promoted to a
>> +  primary server is called a ...
> 
> Yeah.
> 
>> How about:
>>
>> + A standby server that must be promoted to a primary server before
>> + accepting connections is called a ...
> 
> How about just reducing it to "A standby server that doesn't accept
> connection is called a ..."?  We don't really need to explain that if
> you do promote the standby it will start accept connections -- do we?
> It should be pretty obvious if you promote a standby, it will cease to
> be a standby in the first place.  This verbiage seems excessive.

Works for me.

Regards,
-- 
-David
david@pgmasters.net



Re: language cleanups in code and docs

From
Ashwin Agrawal
Date:
On Wed, Jun 17, 2020 at 9:27 AM David Steele <david@pgmasters.net> wrote:
On 6/17/20 12:08 PM, Magnus Hagander wrote:
> On Wed, Jun 17, 2020 at 4:15 PM Andrew Dunstan
> <andrew.dunstan@2ndquadrant.com <mailto:andrew.dunstan@2ndquadrant.com>>
>
>     I'm not sure I like doing s/Black/Block/ here. It reads oddly. There are
>     too many other uses of Block in the sources. Forbidden might be a better
>     substitution, or Banned maybe. BanList is even less characters than
>     BlackList.
>
> I'd be OK with either of those really -- I went with block because it
> was the easiest one :)
>
> Not sure the number of characters is the important part :) Banlist does
> make sense to me for other reasons though -- it's what it is, isn't it?
> It bans those oids from being used in the current session -- I don't
> think there's any struggle to "make that sentence work", which means
> that seems like the relevant term.

I've seen also seen allowList/denyList as an alternative. I do agree
that blockList is a bit confusing since we often use block in a very
different context.

+1 for allowList/denyList as alternative

> I do think it's worth doing -- it's a small round of changes, and it
> doesn't change anything user-exposed, so the cost for us is basically zero.

+1

Agree number of occurrences for whitelist and blacklist are not many, so cleaning these would be helpful and patches already proposed for it

git grep whitelist | wc -l
10
git grep blacklist | wc -l
40

Thanks a lot for language cleanups. Greenplum, fork of PostgreSQL, wishes to perform similar cleanups and upstream doing it really helps us downstream.

Re: language cleanups in code and docs

From
Thomas Munro
Date:
On Wed, Jun 17, 2020 at 10:32 PM Magnus Hagander <magnus@hagander.net> wrote:
> In looking at this I realize we also have exactly one thing referred to as "blacklist" in our codebase, which is the
"enumblacklist" (and then a small internal variable in pgindent). AFAICT, it's not actually exposed to userspace
anywhere,so we could probably make the attached change to blocklist at no "cost" (the only thing changed is the name of
thehash table, and we definitely change things like that in normal releases with no specific thought on backwards
compat).

+1

Hmm, can we find a more descriptive name for this mechanism?  What
about calling it the "uncommitted enum table"?  See attached.

Attachment

Re: language cleanups in code and docs

From
Magnus Hagander
Date:
On Wed, Oct 21, 2020 at 11:23 PM Thomas Munro <thomas.munro@gmail.com> wrote:
>
> On Wed, Jun 17, 2020 at 10:32 PM Magnus Hagander <magnus@hagander.net> wrote:
> > In looking at this I realize we also have exactly one thing referred to as "blacklist" in our codebase, which is
the"enum blacklist" (and then a small internal variable in pgindent). AFAICT, it's not actually exposed to userspace
anywhere,so we could probably make the attached change to blocklist at no "cost" (the only thing changed is the name of
thehash table, and we definitely change things like that in normal releases with no specific thought on backwards
compat).
>
> +1
>
> Hmm, can we find a more descriptive name for this mechanism?  What
> about calling it the "uncommitted enum table"?  See attached.

Thanks for picking this one up again!

Agreed, that's a much better choice.

The term itself is a bit of a mouthful, but it does describe what it
is in a much more clear way than what the old term did anyway.

Maybe consider just calling it "uncomitted enums", which would as a
bonus have it not end up talking about uncommittedenumtablespace which
gets hits on searches for tablespace.. Though I'm not sure that's
important.

I'm +1 to the change with or without that adjustment.

As for the code, I note that:
+       /* Set up the enum table if not already done in this transaction */

forgets to say it's *uncomitted* enum table -- which is the important
part of I believe.

And
+ * Test if the given enum value is in the table of blocked enums.

should probably talk about uncommitted rather than blocked?

--
 Magnus Hagander
 Me: https://www.hagander.net/
 Work: https://www.redpill-linpro.com/



Re: language cleanups in code and docs

From
Thomas Munro
Date:
On Wed, Nov 4, 2020 at 4:10 AM Magnus Hagander <magnus@hagander.net> wrote:
> On Wed, Oct 21, 2020 at 11:23 PM Thomas Munro <thomas.munro@gmail.com> wrote:
> > Hmm, can we find a more descriptive name for this mechanism?  What
> > about calling it the "uncommitted enum table"?  See attached.
>
> Thanks for picking this one up again!
>
> Agreed, that's a much better choice.
>
> The term itself is a bit of a mouthful, but it does describe what it
> is in a much more clear way than what the old term did anyway.
>
> Maybe consider just calling it "uncomitted enums", which would as a
> bonus have it not end up talking about uncommittedenumtablespace which
> gets hits on searches for tablespace.. Though I'm not sure that's
> important.
>
> I'm +1 to the change with or without that adjustment.

Cool.  I went with your suggestion.

> As for the code, I note that:
> +       /* Set up the enum table if not already done in this transaction */
>
> forgets to say it's *uncomitted* enum table -- which is the important
> part of I believe.

Fixed.

> And
> + * Test if the given enum value is in the table of blocked enums.
>
> should probably talk about uncommitted rather than blocked?

Fixed.

And pushed.



Re: language cleanups in code and docs

From
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
Magnus Hagander <magnus@hagander.net> writes:

> In looking at this I realize we also have exactly one thing referred to as
> "blacklist" in our codebase, which is the "enum blacklist" (and then a
> small internal variable in pgindent).

Here's a patch that renames the @whitelist and %blacklist variables in
pgindent to @additional and %excluded, and adjusts the comments to
match.

- ilmari
-- 
"The surreality of the universe tends towards a maximum" -- Skud's Law
"Never formulate a law or axiom that you're not prepared to live with
 the consequences of."                              -- Skud's Meta-Law

From 6525826bdf87ce02bd0a1648f94c7122290907f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= <ilmari@ilmari.org>
Date: Tue, 5 Jan 2021 00:10:07 +0000
Subject: [PATCH] Rename whitelist/blacklist in pgindent to additional/excluded

---
 src/tools/pgindent/pgindent | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/tools/pgindent/pgindent b/src/tools/pgindent/pgindent
index 4124d27dea..feb02067c5 100755
--- a/src/tools/pgindent/pgindent
+++ b/src/tools/pgindent/pgindent
@@ -54,12 +54,12 @@ $excludes ||= "$code_base/src/tools/pgindent/exclude_file_patterns"
 # some names we want to treat like typedefs, e.g. "bool" (which is a macro
 # according to <stdbool.h>), and may include some names we don't want
 # treated as typedefs, although various headers that some builds include
-# might make them so.  For the moment we just hardwire a whitelist of names
-# to add and a blacklist of names to remove; eventually this may need to be
+# might make them so.  For the moment we just hardwire a list of names
+# to add and a list of names to exclude; eventually this may need to be
 # easier to configure.  Note that the typedefs need trailing newlines.
-my @whitelist = ("bool\n");
+my @additional = ("bool\n");
 
-my %blacklist = map { +"$_\n" => 1 } qw(
+my %excluded = map { +"$_\n" => 1 } qw(
   ANY FD_SET U abs allocfunc boolean date digit ilist interval iterator other
   pointer printfunc reference string timestamp type wrap
 );
@@ -134,11 +134,11 @@ sub load_typedefs
         }
     }
 
-    # add whitelisted entries
-    push(@typedefs, @whitelist);
+    # add additional entries
+    push(@typedefs, @additional);
 
-    # remove blacklisted entries
-    @typedefs = grep { !$blacklist{$_} } @typedefs;
+    # remove excluded entries
+    @typedefs = grep { !$excluded{$_} } @typedefs;
 
     # write filtered typedefs
     my $filter_typedefs_fh = new File::Temp(TEMPLATE => "pgtypedefXXXXX");
-- 
2.29.2


Re: language cleanups in code and docs

From
Thomas Munro
Date:
On Tue, Jan 5, 2021 at 1:12 PM Dagfinn Ilmari Mannsåker
<ilmari@ilmari.org> wrote:
> Magnus Hagander <magnus@hagander.net> writes:
> > In looking at this I realize we also have exactly one thing referred to as
> > "blacklist" in our codebase, which is the "enum blacklist" (and then a
> > small internal variable in pgindent).
>
> Here's a patch that renames the @whitelist and %blacklist variables in
> pgindent to @additional and %excluded, and adjusts the comments to
> match.

Pushed.  Thanks!



Re: language cleanups in code and docs

From
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
Thomas Munro <thomas.munro@gmail.com> writes:

> On Tue, Jan 5, 2021 at 1:12 PM Dagfinn Ilmari Mannsåker
> <ilmari@ilmari.org> wrote:
>> Magnus Hagander <magnus@hagander.net> writes:
>> > In looking at this I realize we also have exactly one thing referred to as
>> > "blacklist" in our codebase, which is the "enum blacklist" (and then a
>> > small internal variable in pgindent).
>>
>> Here's a patch that renames the @whitelist and %blacklist variables in
>> pgindent to @additional and %excluded, and adjusts the comments to
>> match.
>
> Pushed.  Thanks!

Thanks!  Just after sending that, I thought to grep for "white\W*list"
as well, and found a few more occurrences that were trivially reworded,
per the attached patch.

- ilmari
-- 
"A disappointingly low fraction of the human race is,
 at any given time, on fire." - Stig Sandbeck Mathisen

From 43e9c60bac7b1702e5be2362a439f67adc8a5e06 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= <ilmari@ilmari.org>
Date: Tue, 5 Jan 2021 00:20:49 +0000
Subject: [PATCH] Replace remaining uses of "whitelist"

Instead describe the action that the list effects, or just use "list"
where the meaning is obvious from context.
---
 contrib/postgres_fdw/postgres_fdw.h    | 2 +-
 contrib/postgres_fdw/shippable.c       | 4 ++--
 src/backend/access/hash/hashvalidate.c | 2 +-
 src/backend/utils/adt/lockfuncs.c      | 2 +-
 src/tools/pginclude/README             | 4 ++--
 5 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/contrib/postgres_fdw/postgres_fdw.h b/contrib/postgres_fdw/postgres_fdw.h
index 277a30f500..19ea27a1bc 100644
--- a/contrib/postgres_fdw/postgres_fdw.h
+++ b/contrib/postgres_fdw/postgres_fdw.h
@@ -77,7 +77,7 @@ typedef struct PgFdwRelationInfo
     bool        use_remote_estimate;
     Cost        fdw_startup_cost;
     Cost        fdw_tuple_cost;
-    List       *shippable_extensions;    /* OIDs of whitelisted extensions */
+    List       *shippable_extensions;    /* OIDs of shippable extensions */
 
     /* Cached catalog information. */
     ForeignTable *table;
diff --git a/contrib/postgres_fdw/shippable.c b/contrib/postgres_fdw/shippable.c
index c43e7e5ec5..b27f82e015 100644
--- a/contrib/postgres_fdw/shippable.c
+++ b/contrib/postgres_fdw/shippable.c
@@ -7,7 +7,7 @@
  * data types are shippable to a remote server for execution --- that is,
  * do they exist and have the same behavior remotely as they do locally?
  * Built-in objects are generally considered shippable.  Other objects can
- * be shipped if they are white-listed by the user.
+ * be shipped if they are declared as such by the user.
  *
  * Note: there are additional filter rules that prevent shipping mutable
  * functions or functions using nonportable collations.  Those considerations
@@ -110,7 +110,7 @@ InitializeShippableCache(void)
  *
  * Right now "shippability" is exclusively a function of whether the object
  * belongs to an extension declared by the user.  In the future we could
- * additionally have a whitelist of functions/operators declared one at a time.
+ * additionally have a list of functions/operators declared one at a time.
  */
 static bool
 lookup_shippable(Oid objectId, Oid classId, PgFdwRelationInfo *fpinfo)
diff --git a/src/backend/access/hash/hashvalidate.c b/src/backend/access/hash/hashvalidate.c
index 8462540017..1e343df0af 100644
--- a/src/backend/access/hash/hashvalidate.c
+++ b/src/backend/access/hash/hashvalidate.c
@@ -312,7 +312,7 @@ check_hash_func_signature(Oid funcid, int16 amprocnum, Oid argtype)
          * that are different from but physically compatible with the opclass
          * datatype.  In some of these cases, even a "binary coercible" check
          * fails because there's no relevant cast.  For the moment, fix it by
-         * having a whitelist of allowed cases.  Test the specific function
+         * having a list of allowed cases.  Test the specific function
          * identity, not just its input type, because hashvarlena() takes
          * INTERNAL and allowing any such function seems too scary.
          */
diff --git a/src/backend/utils/adt/lockfuncs.c b/src/backend/utils/adt/lockfuncs.c
index 9f2c4946c9..0db8be6c91 100644
--- a/src/backend/utils/adt/lockfuncs.c
+++ b/src/backend/utils/adt/lockfuncs.c
@@ -644,7 +644,7 @@ pg_isolation_test_session_is_blocked(PG_FUNCTION_ARGS)
     /*
      * Check if blocked_pid is waiting for a safe snapshot.  We could in
      * theory check the resulting array of blocker PIDs against the
-     * interesting PIDs whitelist, but since there is no danger of autovacuum
+     * interesting PIDs list, but since there is no danger of autovacuum
      * blocking GetSafeSnapshot there seems to be no point in expending cycles
      * on allocating a buffer and searching for overlap; so it's presently
      * sufficient for the isolation tester's purposes to use a single element
diff --git a/src/tools/pginclude/README b/src/tools/pginclude/README
index a067c7f472..49eb4b6907 100644
--- a/src/tools/pginclude/README
+++ b/src/tools/pginclude/README
@@ -64,7 +64,7 @@ with no prerequisite headers other than postgres.h (or postgres_fe.h
 or c.h, as appropriate).
 
 A small number of header files are exempted from this requirement,
-and are whitelisted in the headerscheck script.
+and are skipped by the headerscheck script.
 
 The easy way to run the script is to say "make -s headerscheck" in
 the top-level build directory after completing a build.  You should
@@ -86,7 +86,7 @@ the project's coding language is C, some people write extensions in C++,
 so it's helpful for include files to be C++-clean.
 
 A small number of header files are exempted from this requirement,
-and are whitelisted in the cpluspluscheck script.
+and are skipped by the cpluspluscheck script.
 
 The easy way to run the script is to say "make -s cpluspluscheck" in
 the top-level build directory after completing a build.  You should
-- 
2.29.2


Re: language cleanups in code and docs

From
Thomas Munro
Date:
On Tue, Jan 5, 2021 at 1:44 PM Dagfinn Ilmari Mannsåker
<ilmari@ilmari.org> wrote:
> Thanks!  Just after sending that, I thought to grep for "white\W*list"
> as well, and found a few more occurrences that were trivially reworded,
> per the attached patch.

Pushed.