[PATCH v1 0/2] document deprecation of log.mailmap=false default

[PATCH v1 0/2] document deprecation of log.mailmap=false default

[Ariadne Conill]

Based on the discussion of the previous patches, we concluded that
changing the default will require a transitional period.

As such, I have introduced a deprecation warning that is printed when
the log builtin commands are used.

Thanks to Junio and everyone else for providing feedback on how to
proceed.

Ariadne Conill (2):
  log: add warning for unspecified log.mailmap setting
  documentation: mention --no-use-mailmap and log.mailmap false setting

 Documentation/config/log.txt |  3 ++-
 Documentation/git-log.txt    |  2 +-
 builtin/log.c                | 17 ++++++++++++++++-
 3 files changed, 19 insertions(+), 3 deletions(-)

-- 
2.17.1

[PATCH v1 1/2] log: add warning for unspecified log.mailmap setting

[Ariadne Conill]

Based on discussions around changing the log.mailmap default to being
enabled, it was decided that a transitional period is required.

Accordingly, we announce this transitional period with a warning
message.

Signed-off-by: Ariadne Conill <ariadne@dereferenced.org>
---
 builtin/log.c | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/builtin/log.c b/builtin/log.c
index 7c8767d3bc..5ee150be04 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -47,7 +47,7 @@ static int default_follow;
 static int default_show_signature;
 static int decoration_style;
 static int decoration_given;
-static int use_mailmap_config;
+static int use_mailmap_config = -1;
 static const char *fmt_patch_subject_prefix = "PATCH";
 static const char *fmt_pretty;
 
@@ -151,6 +151,16 @@ static void cmd_log_init_defaults(struct rev_info *rev)
 		parse_date_format(default_date_mode, &rev->date_mode);
 }
 
+static char warn_unspecified_mailmap_msg[] =
+N_("log.mailmap is not set; its implicit value will change in an\n"
+   "upcoming release. To squelch this message and preserve current\n"
+   "behaviour, set the log.mailmap configuration value to false.\n"
+   "\n"
+   "To squelch this message and adopt the new behaviour now, set the\n"
+   "log.mailmap configuration value to true.\n"
+   "\n"
+   "See 'git help config' and search for 'log.mailmap' for further information.");
+
 static void cmd_log_init_finish(int argc, const char **argv, const char *prefix,
 			 struct rev_info *rev, struct setup_revision_opt *opt)
 {
@@ -188,6 +198,11 @@ static void cmd_log_init_finish(int argc, const char **argv, const char *prefix,
 			     PARSE_OPT_KEEP_ARGV0 | PARSE_OPT_KEEP_UNKNOWN |
 			     PARSE_OPT_KEEP_DASHDASH);
 
+	if (mailmap < 0) {
+		warning("%s\n", _(warn_unspecified_mailmap_msg));
+		mailmap = 0;
+	}
+
 	if (quiet)
 		rev->diffopt.output_format |= DIFF_FORMAT_NO_OUTPUT;
 	argc = setup_revisions(argc, argv, rev, opt);
-- 
2.17.1

[PATCH v1 2/2] documentation: mention --no-use-mailmap and log.mailmap false setting

[Ariadne Conill]

The log.mailmap setting may be explicitly set to false, which disables
the mailmap feature implicity. In practice, doing so is equivalent to
always using the previously undocumented --no-use-mailmap option on the
command line.

Accordingly, we document both the existence of --no-use-mailmap as
well as briefly discuss the equivalence of it to log.mailmap=False.

Signed-off-by: Ariadne Conill <ariadne@dereferenced.org>
---
 Documentation/config/log.txt | 3 ++-
 Documentation/git-log.txt    | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt
index 78d9e4453a..7798e10cb0 100644
--- a/Documentation/config/log.txt
+++ b/Documentation/config/log.txt
@@ -40,4 +40,5 @@ log.showSignature::
 
 log.mailmap::
 	If true, makes linkgit:git-log[1], linkgit:git-show[1], and
-	linkgit:git-whatchanged[1] assume `--use-mailmap`.
+	linkgit:git-whatchanged[1] assume `--use-mailmap`, otherwise
+	assume `--no-use-mailmap`. False by default.
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index b02e922dc3..b406bc4c48 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -49,7 +49,7 @@ OPTIONS
 	Print out the ref name given on the command line by which each
 	commit was reached.
 
---use-mailmap::
+--[no-]use-mailmap::
 	Use mailmap file to map author and committer names and email
 	addresses to canonical real names and email addresses. See
 	linkgit:git-shortlog[1].
-- 
2.17.1

Re: [PATCH v1 0/2] document deprecation of log.mailmap=false default

[Junio C Hamano]

Ariadne Conill <ariadne@dereferenced.org> writes:

> Based on the discussion of the previous patches, we concluded that
> changing the default will require a transitional period.

OK.

> As such, I have introduced a deprecation warning that is printed when
> the log builtin commands are used.

... used when the user did not configure and did not give --[no-]use-mailmap
option from the command line, right?  Otherwise the warning would be annoying.

Have you run the test suite before posting?  To me, at least t0203,
t4212, t7006 and t9700 seem to be having trouble with this change,
that may need adjusting.

0203.1 expects that "git show" gives nothing to its standard error
stream.  Perhaps something like this should serve as a good
workaround.

diff --git a/t/t0203-gettext-setlocale-sanity.sh b/t/t0203-gettext-setlocale-sanity.sh
index 0ce1f22eff..76f774c8b8 100755
--- a/t/t0203-gettext-setlocale-sanity.sh
+++ b/t/t0203-gettext-setlocale-sanity.sh
@@ -10,7 +10,7 @@ test_description="The Git C functions aren't broken by setlocale(3)"
 test_expect_success 'git show a ISO-8859-1 commit under C locale' '
 	. "$TEST_DIRECTORY"/t3901/8859-1.txt &&
 	test_commit "iso-c-commit" iso-under-c &&
-	git show >out 2>err &&
+	git show --use-mailmap >out 2>err &&
 	test_must_be_empty err &&
 	grep -q "iso-c-commit" out
 '


4212.3 is the same way.

4212.4 raises an interesting question.  It wants to see the output
of this command:

	git log --format="%an+%ae+%ad" broken_email >actual.out 2>actual.err &&

The question is, when the user explicitly asked for the "true"
identity values (not the mapped one via %aN, %aE and their friends),
if --use-mailmap should affect the outcome?

A secondary question is if we should be issuing a warning against
this command line in the first place, if the answer to the above
question is "no" (i.e. --[no-]use-mailmap, and the future default
switch, do not affect the outcome).  There is no point issuing a
warning if the command line is already future-proofed.

7006.43 (among others) expects its "colorful" shell helper function
to be a reliable way to detect if color escape sequence is in use in
the output but the helper only reads the first line and expects it
to always begin with the colored "commit 0c9f6db7183a...", which fails
when an error or a warning message comes first.  I think the best fix
there should be to make the helper more robust, perhaps by borrowing
ideas from test-lib-functions.sh::test_decode_color, i.e. find byte
sequence "\033[m" in there (I think assuming the presence of RESET
sequence alone is sufficient for the purpose of t7006 tests that
wants to see "have we tried to color or emit non-colored output?".

A possible workaround for 9007 would be to set log.mailmap=true in
the set-up step, but there may be a better alternative.

diff --git a/t/t9700-perl-git.sh b/t/t9700-perl-git.sh
index 102c133112..a7a336947d 100755
--- a/t/t9700-perl-git.sh
+++ b/t/t9700-perl-git.sh
@@ -36,6 +36,7 @@ test_expect_success \
      echo "changed file 1" > file1 &&
      git commit -a -m "second commit" &&
 
+     git config log.mailmap true &&
      git config --add color.test.slot1 green &&
      git config --add test.string value &&
      git config --add test.dupstring value1 &&


There may be issues with other tests.  I didn't do any exhaustive
vetting.

Thanks.

Re: [PATCH v1 0/2] document deprecation of log.mailmap=false default

[Ariadne Conill]

Hello,

On Fri, Jul 12, 2019 at 12:50 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Ariadne Conill <ariadne@dereferenced.org> writes:
>
> > Based on the discussion of the previous patches, we concluded that
> > changing the default will require a transitional period.
>
> OK.
>
> > As such, I have introduced a deprecation warning that is printed when
> > the log builtin commands are used.
>
> ... used when the user did not configure and did not give --[no-]use-mailmap
> option from the command line, right?  Otherwise the warning would be annoying.

Yes, the default state is changed to -1, which using the command line
options or explicitly configuring the option would change to either 0
or 1.

> Have you run the test suite before posting?  To me, at least t0203,
> t4212, t7006 and t9700 seem to be having trouble with this change,
> that may need adjusting.

I ran parts of the testsuite, but I can go through the whole thing and
will fix the fallout.

> 0203.1 expects that "git show" gives nothing to its standard error
> stream.  Perhaps something like this should serve as a good
> workaround.
>
> diff --git a/t/t0203-gettext-setlocale-sanity.sh b/t/t0203-gettext-setlocale-sanity.sh
> index 0ce1f22eff..76f774c8b8 100755
> --- a/t/t0203-gettext-setlocale-sanity.sh
> +++ b/t/t0203-gettext-setlocale-sanity.sh
> @@ -10,7 +10,7 @@ test_description="The Git C functions aren't broken by setlocale(3)"
>  test_expect_success 'git show a ISO-8859-1 commit under C locale' '
>         . "$TEST_DIRECTORY"/t3901/8859-1.txt &&
>         test_commit "iso-c-commit" iso-under-c &&
> -       git show >out 2>err &&
> +       git show --use-mailmap >out 2>err &&
>         test_must_be_empty err &&
>         grep -q "iso-c-commit" out
>  '
>
>
> 4212.3 is the same way.
>
> 4212.4 raises an interesting question.  It wants to see the output
> of this command:
>
>         git log --format="%an+%ae+%ad" broken_email >actual.out 2>actual.err &&
>
> The question is, when the user explicitly asked for the "true"
> identity values (not the mapped one via %aN, %aE and their friends),
> if --use-mailmap should affect the outcome?

I don't think it should.

> A secondary question is if we should be issuing a warning against
> this command line in the first place, if the answer to the above
> question is "no" (i.e. --[no-]use-mailmap, and the future default
> switch, do not affect the outcome).  There is no point issuing a
> warning if the command line is already future-proofed.

I will disable the warning if a custom format is specified.

> 7006.43 (among others) expects its "colorful" shell helper function
> to be a reliable way to detect if color escape sequence is in use in
> the output but the helper only reads the first line and expects it
> to always begin with the colored "commit 0c9f6db7183a...", which fails
> when an error or a warning message comes first.  I think the best fix
> there should be to make the helper more robust, perhaps by borrowing
> ideas from test-lib-functions.sh::test_decode_color, i.e. find byte
> sequence "\033[m" in there (I think assuming the presence of RESET
> sequence alone is sufficient for the purpose of t7006 tests that
> wants to see "have we tried to color or emit non-colored output?".

The colorful shell helper function irritates me from time to time with
that sort of thing.  I might look into fixing it, but I think for now
it makes more sense to just defang those tests by killing the warning.

A thought I had was to perhaps use isatty(STDERR_FILENO) to determine
if stderr is attached to a terminal session and only issue the warning
in that case.  What do you think?  It should fix all of these tests.

> A possible workaround for 9007 would be to set log.mailmap=true in
> the set-up step, but there may be a better alternative.
>
> diff --git a/t/t9700-perl-git.sh b/t/t9700-perl-git.sh
> index 102c133112..a7a336947d 100755
> --- a/t/t9700-perl-git.sh
> +++ b/t/t9700-perl-git.sh
> @@ -36,6 +36,7 @@ test_expect_success \
>       echo "changed file 1" > file1 &&
>       git commit -a -m "second commit" &&
>
> +     git config log.mailmap true &&
>       git config --add color.test.slot1 green &&
>       git config --add test.string value &&
>       git config --add test.dupstring value1 &&

This seems reasonable.

> There may be issues with other tests.  I didn't do any exhaustive
> vetting.

Thanks wholeheartedly for all of your help so far, I know there are
many git users who will be very happy once all of this work is done
(basically anyone who has changed their name).

Ariadne

Re: [PATCH v1 0/2] document deprecation of log.mailmap=false default

[Junio C Hamano]

Ariadne Conill <ariadne@dereferenced.org> writes:

>> 4212.4 raises an interesting question.  It wants to see the output
>> of this command:
>>
>>         git log --format="%an+%ae+%ad" broken_email >actual.out 2>actual.err &&
>>
>> The question is, when the user explicitly asked for the "true"
>> identity values (not the mapped one via %aN, %aE and their friends),
>> if --use-mailmap should affect the outcome?
>
> I don't think it should.
>
>> A secondary question is if we should be issuing a warning against
>> this command line in the first place, if the answer to the above
>> question is "no" (i.e. --[no-]use-mailmap, and the future default
>> switch, do not affect the outcome).  There is no point issuing a
>> warning if the command line is already future-proofed.
>
> I will disable the warning if a custom format is specified.

I briefly thought that this is tricky enough that we should wait for
other people to chime in before casting the decision in stone.  But
we can continue with what we consider the better variant in the
meantime.

> A thought I had was to perhaps use isatty(STDERR_FILENO) to determine
> if stderr is attached to a terminal session and only issue the warning
> in that case.  What do you think?  It should fix all of these tests.

Some of them but it should not affect that one, which is run under
test_terminal, as the whole point of that test helper is to see how
we behave in a terminal ;-)

> Thanks wholeheartedly for all of your help so far, I know there are
> many git users who will be very happy once all of this work is done
> (basically anyone who has changed their name).

Thanks.