[v3,2/4] doc: provide guidance on user.name format
diff mbox series

Message ID 20191102192615.10013-3-sandals@crustytoothpaste.net
State New
Headers show
Series
  • Documentation for common user misconceptions
Related show

Commit Message

brian m. carlson Nov. 2, 2019, 7:26 p.m. UTC
It's a frequent misconception that the user.name variable controls
authentication in some way, and as a result, beginning users frequently
attempt to change it when they're having authentication troubles.
Document that the convention is that this variable represents some form
of a human's personal name, although that is not required.  In addition,
address concerns about whether Unicode is supported.

Use the term "personal name" as this is likely to draw the intended
contrast, be applicable across cultures which may have different naming
conventions, and be easily understandable to people who do not speak
English as their first language.  Indicate that "some form" is
conventionally used, as people may use a nickname or preferred name
instead of a full legal name.

Point users who may be confused about authentication to an appropriate
configuration option instead.  Provide a shortened form of this
information in the configuration option description.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/config/user.txt | 7 ++++++-
 Documentation/git-commit.txt  | 6 ++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

Comments

Jakub Narebski Nov. 3, 2019, 1:13 p.m. UTC | #1
"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> It's a frequent misconception that the user.name variable controls
> authentication in some way, and as a result, beginning users frequently
> attempt to change it when they're having authentication troubles.
> Document that the convention is that this variable represents some form
> of a human's personal name, although that is not required.  In addition,
> address concerns about whether Unicode is supported.
>
> Use the term "personal name" as this is likely to draw the intended
> contrast, be applicable across cultures which may have different naming
> conventions, and be easily understandable to people who do not speak
> English as their first language.  Indicate that "some form" is
> conventionally used, as people may use a nickname or preferred name
> instead of a full legal name.

This reminds me of "Personal names around the world" by W3C
https://www.w3.org/International/questions/qa-personal-names

>
> Point users who may be confused about authentication to an appropriate
> configuration option instead.  Provide a shortened form of this
> information in the configuration option description.
>
> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>

I like this change!  Un-confusing users is always a win.

> ---
>  Documentation/config/user.txt | 7 ++++++-
>  Documentation/git-commit.txt  | 6 ++++++
>  2 files changed, 12 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt
> index a1f80e823c..f0edb06329 100644
> --- a/Documentation/config/user.txt
> +++ b/Documentation/config/user.txt
> @@ -13,7 +13,12 @@ committer.email::
>  	Also, all of these can be overridden by the `GIT_AUTHOR_NAME`,
>  	`GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`,
>  	`GIT_COMMITTER_EMAIL` and `EMAIL` environment variables.
> -	See linkgit:git-commit[1] for more information.
> ++
> +Note that the `name` forms of these variables conventionally refer to
> +some form of a personal name.
> +See linkgit:git-commit[1] for more information on these settings and
> +the `credential.username` option if you're looking for authentication
> +credentials instead.

Minor nit: should this be one paragraph or two - the linebreak after "of
a personal name." looks a bit strange?

No need for a change: just idly wondering.

>  
>  user.useConfigOnly::
>  	Instruct Git to avoid trying to guess defaults for `user.email`
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index f684f7fdc2..3a69d82d52 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -467,6 +467,12 @@ if set:
>  
>  (nb "<", ">" and "\n"s are stripped)
>  
> +The author and committer names are by convention some form of a personal name
> +(that is, the name by which other humans refer to you), although Git does not
> +enforce or require any particular form. Arbitrary Unicode may be used, subject
> +to the constraints listed above. This name has no effect on authentication; for
> +that, see the `credential.username` variable in linkgit::git-config[1].

Just ensuring that I understand it correctly: by "constraints" you mean
stripping of "<", ">" and "\n" (and by implication "\0")?

Should we say anything about encoding?

> +
>  In case (some of) these environment variables are not set, the information
>  is taken from the configuration items user.name and user.email, or, if not
>  present, the environment variable EMAIL, or, if that is not set,

Best,
brian m. carlson Nov. 3, 2019, 7:23 p.m. UTC | #2
On 2019-11-03 at 13:13:57, Jakub Narebski wrote:
> This reminds me of "Personal names around the world" by W3C
> https://www.w3.org/International/questions/qa-personal-names

I hadn't read that document before, but it's definitely the approach I
was going for.  People all over the world use Git, and we should make it
as usable for all of those people as we can.

> Minor nit: should this be one paragraph or two - the linebreak after "of
> a personal name." looks a bit strange?
> 
> No need for a change: just idly wondering.

Good question.  I had explained this in my original patch but had to
reformat the patch and forgot to include this.

The existing text uses a line break after each sentence, and in AsciiDoc
that doesn't introduce a new paragraph; only a blank line does that.  I
opted to keep this consistent with the rest of the description of this
item.

> Just ensuring that I understand it correctly: by "constraints" you mean
> stripping of "<", ">" and "\n" (and by implication "\0")?

Yes, that's correct.

> Should we say anything about encoding?

I don't think it's necessary; since we told people that arbitrary
Unicode is permitted, hopefully they will determine that they should use
UTF-8, or, for Windows environment variables, UTF-16.  Unfortunately,
there's not a good way to get UTF-8 environment variables in Windows, so
"Unicode" is the best we can do there.

I'm happy to gloss over the fact that they can use something else
because (a) while they can, they should not and (b) if they do, they'll
know that they're obviously restricted to that subset of Unicode.

Patch
diff mbox series

diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt
index a1f80e823c..f0edb06329 100644
--- a/Documentation/config/user.txt
+++ b/Documentation/config/user.txt
@@ -13,7 +13,12 @@  committer.email::
 	Also, all of these can be overridden by the `GIT_AUTHOR_NAME`,
 	`GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`,
 	`GIT_COMMITTER_EMAIL` and `EMAIL` environment variables.
-	See linkgit:git-commit[1] for more information.
++
+Note that the `name` forms of these variables conventionally refer to
+some form of a personal name.
+See linkgit:git-commit[1] for more information on these settings and
+the `credential.username` option if you're looking for authentication
+credentials instead.
 
 user.useConfigOnly::
 	Instruct Git to avoid trying to guess defaults for `user.email`
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index f684f7fdc2..3a69d82d52 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -467,6 +467,12 @@  if set:
 
 (nb "<", ">" and "\n"s are stripped)
 
+The author and committer names are by convention some form of a personal name
+(that is, the name by which other humans refer to you), although Git does not
+enforce or require any particular form. Arbitrary Unicode may be used, subject
+to the constraints listed above. This name has no effect on authentication; for
+that, see the `credential.username` variable in linkgit::git-config[1].
+
 In case (some of) these environment variables are not set, the information
 is taken from the configuration items user.name and user.email, or, if not
 present, the environment variable EMAIL, or, if that is not set,