Re: [PATCH 1/3] Documentation: use allowlist and denylist

From: Jeff King <peff@peff.net>
Date: Jul 13, 2022, 15:21 UTC
Message-ID: <Ys7i/GWSNRHqSZNQ@coredump.intra.peff.net>
In-Reply-To: <ec81aac05c40318755f5311a20e8f9cc55d289fc.1657718450.git.gitgitgadget@gmail.com>

On Wed, Jul 13, 2022 at 01:20:48PM +0000, Derrick Stolee via GitGitGadget wrote:

Show 6 quoted lines

> Using "allowlist" and "denylist" is a more precise definition of the
> functionality they provide. The previous color-based words assume
> cultural interpretation to provide the meaning.
> 
> Focus on replacements in the Documentation/ directory since these are
> not functional uses.

Thanks, the direction looks reasonable to me. I knew at least about the one for protocol.*, which I think I introduced, and had been meaning to grep for others.

I think you need some grammatical fixups, though. E.g.:

Show 10 quoted lines

> diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
> index fdc28c041c7..ff74a90aead 100644
> --- a/Documentation/git-daemon.txt
> +++ b/Documentation/git-daemon.txt
> @@ -33,7 +33,7 @@ It verifies that the directory has the magic file "git-daemon-export-ok", and
>  it will refuse to export any Git directory that hasn't explicitly been marked
>  for export this way (unless the `--export-all` parameter is specified). If you
>  pass some directory paths as 'git daemon' arguments, you can further restrict
> -the offers to a whitelist comprising of those.
> +the offers to a allowlist comprising of those.

You'd want s/a/an/ here.

Show 11 quoted lines

> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 302607a4967..384718ee677 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -887,7 +887,7 @@ for full details.
>  	protocols has `protocol.<name>.allow` set to `always`
>  	(overriding any existing configuration). In other words, any
>  	protocol not mentioned will be disallowed (i.e., this is a
> -	whitelist, not a blacklist). See the description of
> +	allowlist, not a denylist). See the description of
>  	`protocol.allow` in linkgit:git-config[1] for more details.

Ditto here.

Show 6 quoted lines

>  'git daemon' as inetd server::
>  	To set up 'git daemon' as an inetd service that handles any
> -	repository under the whitelisted set of directories, /pub/foo
> +	repository under the allowlisted set of directories, /pub/foo
>  	and /pub/bar, place an entry like the following into
>  	/etc/inetd all on one line:

This one is more gut feeling. Somehow "allowlisted" as an adjective seems more awkward than "whitelisted". Probably because I've just seen "whitelisted" so many more times. Or maybe it just crosses my personal line of too many syllables. ;)

I don't know if there's an easy way around it. I don't have a suggestion that's better than "allowlist" for the general term, and we want to use the terms consistently. You could probably write it as:

  ...any repository under the set of directories in the allowlist...

but I'm sure somebody probably likes that less. :) So I register it only as a suggestion, not a request for a change.

-Peff