[v2,1/3] doc: provide guidance on user.name format
diff mbox series

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

Commit Message

brian m. carlson Oct. 17, 2019, 12:53 a.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.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/git-commit-tree.txt | 6 ++++++
 1 file changed, 6 insertions(+)

Comments

Jeff King Oct. 17, 2019, 5:40 a.m. UTC | #1
On Thu, Oct 17, 2019 at 12:53:28AM +0000, brian m. carlson wrote:

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

I think this is a good distinction to draw, but...

>  Documentation/git-commit-tree.txt | 6 ++++++
>  1 file changed, 6 insertions(+)

...I was surprised to see it here, where I think most users wouldn't
find it. Would it make sense in git-commit(1), or in the description of
the user.name config?

-Peff
Junio C Hamano Oct. 17, 2019, 7:39 a.m. UTC | #2
Jeff King <peff@peff.net> writes:

> I think this is a good distinction to draw, but...
>
>>  Documentation/git-commit-tree.txt | 6 ++++++
>>  1 file changed, 6 insertions(+)
>
> ...I was surprised to see it here, where I think most users wouldn't
> find it. Would it make sense in git-commit(1), or in the description of
> the user.name config?

Yeah, I had the same reaction as you had, both positive and negative
(eh, rather "surprised").
brian m. carlson Oct. 17, 2019, 10:20 p.m. UTC | #3
On 2019-10-17 at 05:40:52, Jeff King wrote:
> On Thu, Oct 17, 2019 at 12:53:28AM +0000, brian m. carlson wrote:
> 
> > 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.
> 
> I think this is a good distinction to draw, but...
> 
> >  Documentation/git-commit-tree.txt | 6 ++++++
> >  1 file changed, 6 insertions(+)
> 
> ...I was surprised to see it here, where I think most users wouldn't
> find it. Would it make sense in git-commit(1), or in the description of
> the user.name config?

So the user.name config description points to git-commit-tree(1), which
describes these in detail, which is why I put it there.  I agree that
it's not a super discoverable place, since I don't know anyone that
actually uses git commit-tree these days.  git-commit(1) doesn't
describe these options at all.

There are, of course, options.  I can add this text into the `user.name`
option in git-config(5) nevertheless, which will likely be more
discoverable, but it will split the documentation on those into two
separate locations.  Or we can leave it in git-commit-tree(1) anyway to
keep it together.

Since you and Junio think this is an odd place (and I agree), I think
it's fine to separate the text out, and I'll reroll with that change
unless someone speaks up strongly against it.
Jeff King Oct. 18, 2019, 5:37 a.m. UTC | #4
On Thu, Oct 17, 2019 at 10:20:38PM +0000, brian m. carlson wrote:

> > >  Documentation/git-commit-tree.txt | 6 ++++++
> > >  1 file changed, 6 insertions(+)
> > 
> > ...I was surprised to see it here, where I think most users wouldn't
> > find it. Would it make sense in git-commit(1), or in the description of
> > the user.name config?
> 
> So the user.name config description points to git-commit-tree(1), which
> describes these in detail, which is why I put it there.  I agree that
> it's not a super discoverable place, since I don't know anyone that
> actually uses git commit-tree these days.  git-commit(1) doesn't
> describe these options at all.

Hmm, yeah. It's a little funny to point users at git-commit-tree, I
think. Some of that documentation may go better in git-commit. But
resolving that may be more than you want to bite off right now.

> There are, of course, options.  I can add this text into the `user.name`
> option in git-config(5) nevertheless, which will likely be more
> discoverable, but it will split the documentation on those into two
> separate locations.  Or we can leave it in git-commit-tree(1) anyway to
> keep it together.

I like the idea of mentioning something about it in user.name, even if
it's more brief ("Note that this doesn't impact the username used for
network authentication; see credential.username" or something).

-Peff

Patch
diff mbox series

diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 4b90b9c12a..c794843634 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -92,6 +92,12 @@  if set:
 
 (nb "<", ">" and "\n"s are stripped)
 
+The author and committer names are by convention some form of a personal name,
+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,