threads / patch / 46737

patchcommit-template: change a message to be more intuitive

Subject: [PATCH] commit-template: change a message to be more intuitive

## tl;dr

15 messages between Sep 12, 2017 and Sep 15, 2017. Diffs are folded; open one to read it.

replies: 14people: 5as markdown or json

Kaartic Sivaraam· Sep 12, 2017, 10:55 UTC · lore

It's not possible to 'touch' the cut-line that is shown when the user requests a patch in his commit template.

So, make the sentence more intuitive.
Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Just a small tweak. May or may not be worth the patch.
 wt-status.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to wt-status.c +1 −1
diff --git a/wt-status.c b/wt-status.c
index 77c27c511..1f54b1df2 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -934,7 +934,7 @@ size_t wt_status_locate_end(const char *s, size_t len)
 
 void wt_status_add_cut_line(FILE *fp)
 {
-	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
+	const char *explanation = _("Do not edit the line above.\nEverything below will be removed.");
 	struct strbuf buf = STRBUF_INIT;
 
 	fprintf(fp, "%c %s", comment_line_char, cut_line);

-- 
2.14.1.1006.g90ad9a07c
Kevin Daudt· Sep 13, 2017, 10:29 UTC · re: Kaartic Sivaraam · lore

Re: [PATCH] commit-template: change a message to be more intuitive

On Tue, Sep 12, 2017 at 04:25:36PM +0530, Kaartic Sivaraam wrote:
> It's not possible to 'touch' the cut-line that is shown when the
> user requests a patch in his commit template.
>

Touching something can also mean to disturb or change something, which is the meaning being used here, so it is not an incorrect use of the word.

> So, make the sentence more intuitive.

I can understand however that it might be not so clear for people with less fluency in English.

Show 24 quoted lines
> 
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  Just a small tweak. May or may not be worth the patch.
> 
>  wt-status.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/wt-status.c b/wt-status.c
> index 77c27c511..1f54b1df2 100644
> --- a/wt-status.c
> +++ b/wt-status.c
> @@ -934,7 +934,7 @@ size_t wt_status_locate_end(const char *s, size_t len)
>  
>  void wt_status_add_cut_line(FILE *fp)
>  {
> -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
> +	const char *explanation = _("Do not edit the line above.\nEverything below will be removed.");
>  	struct strbuf buf = STRBUF_INIT;
>  
>  	fprintf(fp, "%c %s", comment_line_char, cut_line);
> -- 
> 2.14.1.1006.g90ad9a07c
>
Jeff King· Sep 13, 2017, 11:20 UTC · re: Kevin Daudt · lore

Re: [PATCH] commit-template: change a message to be more intuitive

On Wed, Sep 13, 2017 at 12:29:15PM +0200, Kevin Daudt wrote:
Show 13 quoted lines
> On Tue, Sep 12, 2017 at 04:25:36PM +0530, Kaartic Sivaraam wrote:
> > It's not possible to 'touch' the cut-line that is shown when the
> > user requests a patch in his commit template.
> > 
> 
> Touching something can also mean to disturb or change something, which
> is the meaning being used here, so it is not an incorrect use of the
> word.
> 
> > So, make the sentence more intuitive.
> 
> I can understand however that it might be not so clear for people with
> less fluency in English.

I agree with both of your points. It is very clear to me as a native speaker, but I can see how it might not be for everyone.

Interestingly, the change here:
> > -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
> > +	const char *explanation = _("Do not edit the line above.\nEverything below will be removed.");

actually seems less clear to me. I think of "edit" as "modify". But obviously it also should not be removed. Perhaps

  Do not modify or remove the line above.
would be the most clear. Or perhaps it is overly verbose.
-Peff
Kaartic Sivaraam· Sep 13, 2017, 12:31 UTC · re: Jeff King · lore

Re: [PATCH] commit-template: change a message to be more intuitive

On Wednesday 13 September 2017 04:50 PM, Jeff King wrote:
Show 14 quoted lines
> I agree with both of your points. It is very clear to me as a native
> speaker, but I can see how it might not be for everyone.
>
> Interestingly, the change here:
>
>>> -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
>>> +	const char *explanation = _("Do not edit the line above.\nEverything below will be removed.");
> actually seems less clear to me. I think of "edit" as "modify". But
> obviously it also should not be removed. Perhaps
>
>    Do not modify or remove the line above.
>
> would be the most clear. Or perhaps it is overly verbose.
>

Seems to be a valid point. Further, it doesn't seem to be too verbose at least to me. So, I'll change the sentence and revert back to the one I use if someone finds it to be verbose.

--- Kaartic

Kaartic Sivaraam· Sep 13, 2017, 13:05 UTC · re: Kaartic Sivaraam · lore

[PATCH v2] commit-template: change a message to be more intuitive

It's not good to use the phrase 'do not touch' to convey the information that the cut-line should not be modified or removed as it could possibly be mis-interpreted by a person who doesn't know that the word 'touch' has the meaning of 'tamper with'. Further, it could make translations a little difficult as it might not have the intended meaning in a few languages when translated as such.

So, use more intuitive terms in the sentence.
Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 wt-status.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to wt-status.c +1 −2
diff --git a/wt-status.c b/wt-status.c
index 77c27c51134d2..be53579760ee7 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -934,7 +934,7 @@ size_t wt_status_locate_end(const char *s, size_t len)
 
 void wt_status_add_cut_line(FILE *fp)
 {
-	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
+	const char *explanation = _("Do not modify or remove the line above.\nEverything below will be removed.");
 	struct strbuf buf = STRBUF_INIT;
 
 	fprintf(fp, "%c %s", comment_line_char, cut_line);

--
https://github.com/git/git/pull/401
Michael J Gruber· Sep 14, 2017, 07:36 UTC · re: Kaartic Sivaraam · lore

Re: [PATCH v2] commit-template: change a message to be more intuitive

Kaartic Sivaraam venit, vidit, dixit 13.09.2017 15:05:
Show 24 quoted lines
> It's not good to use the phrase 'do not touch' to convey the information
> that the cut-line should not be modified or removed as it could possibly
> be mis-interpreted by a person who doesn't know that the word 'touch' has
> the meaning of 'tamper with'. Further, it could make translations a little
> difficult as it might not have the intended meaning in a few languages when
> translated as such.
> 
> So, use more intuitive terms in the sentence.
> 
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  wt-status.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/wt-status.c b/wt-status.c
> index 77c27c51134d2..be53579760ee7 100644
> --- a/wt-status.c
> +++ b/wt-status.c
> @@ -934,7 +934,7 @@ size_t wt_status_locate_end(const char *s, size_t len)
>  
>  void wt_status_add_cut_line(FILE *fp)
>  {
> -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
> +	const char *explanation = _("Do not modify or remove the line above.\nEverything below will be removed.");

I don't want to complicate things. But now - due to the repeated usage of "remove" - these two sentences seem to be connected by an invisible "or else" ("will" vs. "would" not withstanding). i.e. "or else everything below will be removed, too", which is wrong. Before, they were separated more clearly.

Also, given all the translations that we have, it seems somewhat strange to try and foresee and workaround possible misunderstandings of commonly used English phrases.

Show 7 quoted lines
>  	struct strbuf buf = STRBUF_INIT;
>  
>  	fprintf(fp, "%c %s", comment_line_char, cut_line);
> 
> --
> https://github.com/git/git/pull/401
>
Kaartic Sivaraam· Sep 14, 2017, 14:17 UTC · re: Michael J Gruber · lore

Re: [PATCH v2] commit-template: change a message to be more intuitive

On Thursday 14 September 2017 01:06 PM, Michael J Gruber wrote:
Show 10 quoted lines
> Kaartic Sivaraam venit, vidit, dixit 13.09.2017 15:05:
>>   void wt_status_add_cut_line(FILE *fp)
>>   {
>> -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
>> +	const char *explanation = _("Do not modify or remove the line above.\nEverything below will be removed.");
> I don't want to complicate things. But now - due to the repeated usage
> of "remove" - these two sentences seem to be connected by an invisible
> "or else" ("will" vs. "would" not withstanding). i.e. "or else
> everything below will be removed, too", which is wrong. Before, they
> were separated more clearly.

At least I don't think they are connected by an invisible "or else" because they appear on different lines,

    #
    # ------------------------ >8 ------------------------
    # Do not modify or remove the line above.
    # Everything below will be removed.
    diff --git a/hook-checks/hooks/applypatch-msg b/hook-checks/hooks/applypatch-msg
    new file mode 100755
    index 0000000..a5d7b84
    --- /dev/null
    +++ b/hook-checks/hooks/applypatch-msg
> Also, given all the translations that we have, it seems somewhat strange
> to try and foresee and workaround possible misunderstandings of commonly
> used English phrases.

I thought the translators wouldn't mind this! If they do, then it's better to drop this patch.

--- Kaartic

Jeff King· Sep 14, 2017, 14:41 UTC · re: Kaartic Sivaraam · lore

Re: [PATCH v2] commit-template: change a message to be more intuitive

On Thu, Sep 14, 2017 at 07:47:51PM +0530, Kaartic Sivaraam wrote:
Show 10 quoted lines
> > > -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
> > > +	const char *explanation = _("Do not modify or remove the line above.\nEverything below will be removed.");
> > I don't want to complicate things. But now - due to the repeated usage
> > of "remove" - these two sentences seem to be connected by an invisible
> > "or else" ("will" vs. "would" not withstanding). i.e. "or else
> > everything below will be removed, too", which is wrong. Before, they
> > were separated more clearly.
> 
> At least I don't think they are connected by an invisible "or else" because
> they appear on different lines,

You could switch out the second "removed" for "ignored", which I think has the same meaning but avoids repeating the same word. So:

  # ------------------------ >8 ------------------------
  # Do not modify or remove the line above.
  # Everything below will be ignored.
(I might say "everything below it" to be more precise).

I dunno. We are deep in bikeshed territory here, and I admit I don't overly care that much in the first place.

-Peff
Junio C Hamano· Sep 15, 2017, 02:18 UTC · re: Jeff King · lore

Re: [PATCH v2] commit-template: change a message to be more intuitive

Jeff King <peff@peff.net> writes:
Show 8 quoted lines
>   # ------------------------ >8 ------------------------
>   # Do not modify or remove the line above.
>   # Everything below will be ignored.
>
> (I might say "everything below it" to be more precise).
>
> I dunno. We are deep in bikeshed territory here, and I admit I don't
> overly care that much in the first place.

So should I drop this topic altogether? My inclination is to declare that "everything below it will be ignored" is the best version and stop reading further updates to this thread ;-)

Kaartic Sivaraam· Sep 15, 2017, 04:50 UTC · re: Junio C Hamano · lore

[PATCH v3] commit-template: change a message to be more intuitive

It's not good to use the phrase 'do not touch' to convey the information that the cut-line should not be modified or removed as it could possibly be mis-interpreted by a person who doesn't know that the word 'touch' has the meaning of 'tamper with'. Further, it could make translations a little difficult as it might not have the intended meaning in a few languages (for which translations don't exist yet) when translated as such.

So, use intuitive terms in the sentence. Replacing the word 'touch' with other terms has introduced the possibility of the following sentence to be mis-interpreted, so change the terms in that too.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Changes in v3:
 
    - changed the wordings of the second sentence as there seemed to be a
      magical 'or else' connecting the two lines.
 
 I didn't expect the least that this would go upto v3. In case anyboy finds
 something wrong with this change too, it's a lot better to drop this altogether
 than going for a v4.
 wt-status.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to wt-status.c +1 −1
diff --git a/wt-status.c b/wt-status.c
index 77c27c511..23e87e74d 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -934,7 +934,7 @@ size_t wt_status_locate_end(const char *s, size_t len)
 
 void wt_status_add_cut_line(FILE *fp)
 {
-	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
+	const char *explanation = _("Do not modify or remove the line above.\nEverything below it will be ignored.");
 	struct strbuf buf = STRBUF_INIT;
 
 	fprintf(fp, "%c %s", comment_line_char, cut_line);

-- 
2.14.1.1006.g90ad9a07c
Michael J Gruber· Sep 15, 2017, 10:00 UTC · re: Kaartic Sivaraam · lore

Re: [PATCH v3] commit-template: change a message to be more intuitive

Kaartic Sivaraam venit, vidit, dixit 15.09.2017 06:50:
Show 21 quoted lines
> It's not good to use the phrase 'do not touch' to convey the information
> that the cut-line should not be modified or removed as it could possibly
> be mis-interpreted by a person who doesn't know that the word 'touch' has
> the meaning of 'tamper with'. Further, it could make translations a little
> difficult as it might not have the intended meaning in a few languages (for
> which translations don't exist yet) when translated as such.
> 
> So, use intuitive terms in the sentence. Replacing the word 'touch' with
> other terms has introduced the possibility of the following sentence to be
> mis-interpreted, so change the terms in that too.
> 
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  Changes in v3:
>  
>     - changed the wordings of the second sentence as there seemed to be a
>       magical 'or else' connecting the two lines.
>  
>  I didn't expect the least that this would go upto v3. In case anyboy finds
>  something wrong with this change too, it's a lot better to drop this altogether
>  than going for a v4.
That happens more often than not :)

Your original intent was to avoid any misunderstandings, and all the comments and iterations made sure that we don't trade one possible source of misunderstanding for another but avoid them all.

I consider v4 to be a strict improvement over the status quo and (as fas as I can see) to serve your original intent as good as possible.

Show 17 quoted lines
>  wt-status.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/wt-status.c b/wt-status.c
> index 77c27c511..23e87e74d 100644
> --- a/wt-status.c
> +++ b/wt-status.c
> @@ -934,7 +934,7 @@ size_t wt_status_locate_end(const char *s, size_t len)
>  
>  void wt_status_add_cut_line(FILE *fp)
>  {
> -	const char *explanation = _("Do not touch the line above.\nEverything below will be removed.");
> +	const char *explanation = _("Do not modify or remove the line above.\nEverything below it will be ignored.");
>  	struct strbuf buf = STRBUF_INIT;
>  
>  	fprintf(fp, "%c %s", comment_line_char, cut_line);
>
Kaartic Sivaraam· Sep 15, 2017, 12:39 UTC · re: Michael J Gruber · lore

Re: [PATCH v3] commit-template: change a message to be more intuitive

On Fri, 2017-09-15 at 12:00 +0200, Michael J Gruber wrote:
> Kaartic Sivaraam venit, vidit, dixit 15.09.2017 06:50:
> > 
> >  I didn't expect the least that this would go upto v3. In case anyboy finds
That's should have been 'anybody'.
Show 5 quoted lines
> >  something wrong with this change too, it's a lot better to drop this altogether
> >  than going for a v4.
> 
> That happens more often than not :)
> 
:)
> Your original intent was to avoid any misunderstandings, and all the
> comments and iterations made sure that we don't trade one possible
> source of misunderstanding for another but avoid them all.
> 
Of course they did. 
> I consider v4 to be a strict improvement over the status quo and (as fas
> as I can see) to serve your original intent as good as possible.

I thought I shouldn't go for a v4 as I feared it might make things worse than better because the original sentence wasn't that confusing in the first place ;-)

-- 
Kaartic
Kaartic Sivaraam· Sep 15, 2017, 01:58 UTC · re: Michael J Gruber · lore

Re: [PATCH v2] commit-template: change a message to be more intuitive

On Thu, 2017-09-14 at 09:36 +0200, Michael J Gruber wrote:
> 
> Also, given all the translations that we have, it seems somewhat strange
> to try and foresee and workaround possible misunderstandings of commonly
> used English phrases.

In case you're trying to say that "Translators have successfully translated the phrase with misunderstanding for many languages" then I have to say that I foresaw the difficulty to translate it in other languages for which a translation does not exist yet (specifically my mother tongue). If that's not useful as it might only be an rare case, then this patch isn't either.

-- 
Kaartic
Kaartic Sivaraam· Sep 13, 2017, 12:29 UTC · re: Kevin Daudt · lore

Re: [PATCH] commit-template: change a message to be more intuitive

On Wednesday 13 September 2017 03:59 PM, Kevin Daudt wrote:
> Touching something can also mean to disturb or change something, which
> is the meaning being used here, so it is not an incorrect use of the
> word.

I do get your point but I should have been clearer in my commit message about the fact that it's a word that could be misinterpreted.

>> So, make the sentence more intuitive.
> I can understand however that it might be not so clear for people with
> less fluency in English.

Not just that, it could also make the translations a little unclear. i.e., the when the words that convey clear meaning in a particular context in english speaker get translated "as such" to another language, they might turn out to become unclear or might even convey a totally different meaning. I'm not sure if is currently happening as I am not familiar with any languages for which translations are currently available but I'm pretty sure that the sentence "Do not touch the line above." would not give a clear meaning when it gets translated "as such" to my native language (Tamil). Of course, it's only a problem if the sentences get translated "as such" but I'm not sure if translators (human/non-human) try do meaningful translations or try to preserve a one-to-one relationship with the words in the source language, either.

--- Kaartic

← back to recent threads