{"thread":{"id":"54301","subject":"[PATCH] Doc: note minimum scissors line length for mailinfo","startedAt":"2020-09-25T20:43:43Z","lastAt":"2020-09-28T23:41:57Z","messageCount":10,"participants":["Evan Gates","jrnieder@gmail.com","Junio C Hamano","Jonathan Nieder","Kevin Daudt"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"406394","messageId":"20200925191659.31375-1-evan.gates@gmail.com","threadId":"54301","inReplyTo":null,"subject":"[PATCH] Doc: note minimum scissors line length for mailinfo","fromName":"Evan Gates","fromEmail":"evan.gates@gmail.com","sentAt":"2020-09-25T19:16:59Z","receivedAt":"2020-09-25T20:43:43Z","isPatch":true,"sender":{"key":"evan.gates@gmail.com","avatar":"https://avatars.githubusercontent.com/u/4196295?v=4"},"body":"There is a comment in is_scissors_line describing the requirements for\na line to be considered a scissors line.  While the existing wording\ncovers most of the requirements, there was no mention of minimum size.\n\nSigned-off-by: Evan Gates <evan.gates@gmail.com>\n---\nThis comes up after I tried to use --8<-- as scissors but git am didn't\nrecognize it because it's only 6 bytes.  I couldn't figure out why until\nI cloned git and checked the source.\n\nI am not subscribed to the list, please cc me in any replies.\n\n Documentation/git-mailinfo.txt | 10 +++++-----\n 1 file changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt\nindex 3bbc731f67..859829d32f 100644\n--- a/Documentation/git-mailinfo.txt\n+++ b/Documentation/git-mailinfo.txt\n@@ -74,11 +74,11 @@ conversion, even with this flag.\n --scissors::\n \tRemove everything in body before a scissors line.  A line that\n \tmainly consists of scissors (either \">8\" or \"8<\") and perforation\n-\t(dash \"-\") marks is called a scissors line, and is used to request\n-\tthe reader to cut the message at that line.  If such a line\n-\tappears in the body of the message before the patch, everything\n-\tbefore it (including the scissors line itself) is ignored when\n-\tthis option is used.\n+\t(dash \"-\") marks and is at least 8 bytes long (\"-- >8 --\") is\n+\tcalled a scissors line, and is used to request the reader to cut\n+\tthe message at that line.  If such a line appears in the body\n+\tof the message before the patch, everything before it (including\n+\tthe scissors line itself) is ignored when this option is used.\n +\n This is useful if you want to begin your message in a discussion thread\n with comments and suggestions on the message you are responding to, and to\n-- \n2.28.0\n\n"},{"id":"406551","messageId":"20200928183559.GA2285677@google.com","threadId":"54301","inReplyTo":"20200925191659.31375-1-evan.gates@gmail.com","subject":"Re: [PATCH] Doc: note minimum scissors line length for mailinfo","fromName":"","fromEmail":"jrnieder@gmail.com","sentAt":"2020-09-28T18:35:59Z","receivedAt":"2020-09-28T18:36:06Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nEvan Gates wrote:\n\n> There is a comment in is_scissors_line describing the requirements for\n> a line to be considered a scissors line.  While the existing wording\n> covers most of the requirements, there was no mention of minimum size.\n>\n> Signed-off-by: Evan Gates <evan.gates@gmail.com>\n> ---\n> This comes up after I tried to use --8<-- as scissors but git am didn't\n> recognize it because it's only 6 bytes.  I couldn't figure out why until\n> I cloned git and checked the source.\n\nThanks for following through.  It's probably worth mentioning this\nexample (\"--8<--\") in the commit message as well.\n\n[...]\n> --- a/Documentation/git-mailinfo.txt\n> +++ b/Documentation/git-mailinfo.txt\n> @@ -74,11 +74,11 @@ conversion, even with this flag.\n>  --scissors::\n>  \tRemove everything in body before a scissors line.  A line that\n>  \tmainly consists of scissors (either \">8\" or \"8<\") and perforation\n> -\t(dash \"-\") marks is called a scissors line, and is used to request\n> -\tthe reader to cut the message at that line.  If such a line\n> -\tappears in the body of the message before the patch, everything\n> -\tbefore it (including the scissors line itself) is ignored when\n> -\tthis option is used.\n> +\t(dash \"-\") marks and is at least 8 bytes long (\"-- >8 --\") is\n\nnit: I think \"characters\" instead of \"bytes\" would focus a bit more on\nthe intent.  It's true that characters and bytes coincide in this\nexample, but using characters might be a bit more in the terms that\nthe user is already thinking in.\n\nBy the way, is this the right criterion?  Perhaps an alternative\nmethod would be to make \"--8<--\" count as a scissors like after all.\nWhat do you think?\n\n> +\tcalled a scissors line, and is used to request the reader to cut\n> +\tthe message at that line.  If such a line appears in the body\n> +\tof the message before the patch, everything before it (including\n> +\tthe scissors line itself) is ignored when this option is used.\n>  +\n>  This is useful if you want to begin your message in a discussion thread\n>  with comments and suggestions on the message you are responding to, and to\n\nWith the commit message and wording tweaks listed above,\nReviewed-by: Jonathan Nieder <jrnieder@gmail.com>\n\nThanks.\n"},{"id":"406554","messageId":"xmqq8sctn332.fsf@gitster.c.googlers.com","threadId":"54301","inReplyTo":"20200928183559.GA2285677@google.com","subject":"Re: [PATCH] Doc: note minimum scissors line length for mailinfo","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-09-28T18:55:29Z","receivedAt":"2020-09-28T18:55:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"jrnieder@gmail.com writes:\n\n>> +\t(dash \"-\") marks and is at least 8 bytes long (\"-- >8 --\") is\n>\n> nit: I think \"characters\" instead of \"bytes\" would focus a bit more on\n> the intent.  It's true that characters and bytes coincide in this\n> example, but using characters might be a bit more in the terms that\n> the user is already thinking in.\n>\n> By the way, is this the right criterion?  Perhaps an alternative\n> method would be to make \"--8<--\" count as a scissors like after all.\n> What do you think?\n\nMildly negative.\n\nIt certainly was fun to declare that users can use anything that\nlook like perforation drawn on paper, and to pile more and more\nheuristics to detect such a line.  But I think, instead of\ndescribing all these details in the manual, telling the users to\nalways write \"-- >8 --\" and nothing else would be a better approach.\n\nIt would save them time.\n\nLet's not waste people's time by encouraging them to be \"creative\"\nin areas that do not make the world a better place.  How flexible\nthey can be when drawing the line to mark the part that recipent\ncan discard does not matter in the end result of their work.\n\nThanks.\n"},{"id":"406555","messageId":"20200928190029.GB2285677@google.com","threadId":"54301","inReplyTo":"xmqq8sctn332.fsf@gitster.c.googlers.com","subject":"Re: [PATCH] Doc: note minimum scissors line length for mailinfo","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2020-09-28T19:00:29Z","receivedAt":"2020-09-28T19:00:34Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n\n> It certainly was fun to declare that users can use anything that\n> look like perforation drawn on paper, and to pile more and more\n> heuristics to detect such a line.  But I think, instead of\n> describing all these details in the manual, telling the users to\n> always write \"-- >8 --\" and nothing else would be a better approach.\n>\n> It would save them time.\n\nAgreed, I think this is a much better direction.\n\nAnother advantage is that it makes us easier to change the heuristics,\nconfident that we are training users to aim for the simple and\nreliable case instead of the edge cases that may need to be tweaked\nover time.\n\nThanks,\nJonathan\n"},{"id":"406557","messageId":"C5Z8UYJS02RM.2UD0R6DCK0KX5@emg-xps","threadId":"54301","inReplyTo":"20200928190029.GB2285677@google.com","subject":"Re: [PATCH] Doc: note minimum scissors line length for mailinfo","fromName":"Evan Gates","fromEmail":"evan.gates@gmail.com","sentAt":"2020-09-28T19:20:31Z","receivedAt":"2020-09-28T19:29:21Z","isPatch":true,"sender":{"key":"evan.gates@gmail.com","avatar":"https://avatars.githubusercontent.com/u/4196295?v=4"},"body":"On Mon Sep 28, 2020 at 12:00 PM PDT, Jonathan Nieder wrote:\n> Junio C Hamano wrote:\n>\n> > It certainly was fun to declare that users can use anything that\n> > look like perforation drawn on paper, and to pile more and more\n> > heuristics to detect such a line.  But I think, instead of\n> > describing all these details in the manual, telling the users to\n> > always write \"-- >8 --\" and nothing else would be a better approach.\n> >\n> > It would save them time.\n>\n> Agreed, I think this is a much better direction.\n>\n> Another advantage is that it makes us easier to change the heuristics,\n> confident that we are training users to aim for the simple and\n> reliable case instead of the edge cases that may need to be tweaked\n> over time.\n\nSounds good to me.  How about:\n\nRemove everything in body before a scissors line (\"-- >8 --\"). The line\nrepresents scissors and perforation marks, and is used to request the\nreader to cut the message at that line.  If that line appears in the\nbody of the message before the patch, everything before it (including\nthe scissors line itself) is ignored when this option is used.\n\nEtiquette question: Should a v2 patch be a new thread or reply to\nthis one?\n"},{"id":"406561","messageId":"20200928193332.GA2986883@alpha","threadId":"54301","inReplyTo":"C5Z8UYJS02RM.2UD0R6DCK0KX5@emg-xps","subject":"Re: [PATCH] Doc: note minimum scissors line length for mailinfo","fromName":"Kevin Daudt","fromEmail":"me@ikke.info","sentAt":"2020-09-28T19:33:32Z","receivedAt":"2020-09-28T19:42:57Z","isPatch":true,"sender":{"key":"me@ikke.info","avatar":"https://avatars.githubusercontent.com/u/135698?v=4"},"body":"On Mon, Sep 28, 2020 at 12:20:31PM -0700, Evan Gates wrote:\n> On Mon Sep 28, 2020 at 12:00 PM PDT, Jonathan Nieder wrote:\n> > Junio C Hamano wrote:\n> >\n> > > It certainly was fun to declare that users can use anything that\n> > > look like perforation drawn on paper, and to pile more and more\n> > > heuristics to detect such a line.  But I think, instead of\n> > > describing all these details in the manual, telling the users to\n> > > always write \"-- >8 --\" and nothing else would be a better approach.\n> > >\n> > > It would save them time.\n> >\n> > Agreed, I think this is a much better direction.\n> >\n> > Another advantage is that it makes us easier to change the heuristics,\n> > confident that we are training users to aim for the simple and\n> > reliable case instead of the edge cases that may need to be tweaked\n> > over time.\n> \n> Sounds good to me.  How about:\n> \n> Remove everything in body before a scissors line (\"-- >8 --\"). The line\n> represents scissors and perforation marks, and is used to request the\n> reader to cut the message at that line.  If that line appears in the\n> body of the message before the patch, everything before it (including\n> the scissors line itself) is ignored when this option is used.\n> \n> Etiquette question: Should a v2 patch be a new thread or reply to\n> this one?\n\nTypically you would reply to this thread, ie, to\n20200925191659.31375-1-evan.gates@gmail.com\n\nKevin\n"},{"id":"406567","messageId":"20200928202035.24218-1-evan.gates@gmail.com","threadId":"54301","inReplyTo":"20200925191659.31375-1-evan.gates@gmail.com","subject":"[PATCH v2] Doc: specify exact scissors line","fromName":"Evan Gates","fromEmail":"evan.gates@gmail.com","sentAt":"2020-09-28T20:20:35Z","receivedAt":"2020-09-28T20:20:41Z","isPatch":true,"sender":{"key":"evan.gates@gmail.com","avatar":"https://avatars.githubusercontent.com/u/4196295?v=4"},"body":"The existing wording covers most of the requirements of a scissors\nline, but there is no mention of the minimum size requirement that led\nto a six character line (\"-->8--\") not counting as a scissors line.\nSpecify the exact line to use (\"-- >8 --\") instead of trying to document\nall the details.\n\nSigned-off-by: Evan Gates <evan.gates@gmail.com>\n---\nChanges in v2:\n- Specify exact line instead of adding text about 8 character minimum\n\n Documentation/git-mailinfo.txt | 7 +++----\n 1 file changed, 3 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt\nindex 3bbc731f67..fbb7d2813f 100644\n--- a/Documentation/git-mailinfo.txt\n+++ b/Documentation/git-mailinfo.txt\n@@ -72,10 +72,9 @@ conversion, even with this flag.\n \tis useful in order to associate commits with mailing list discussions.\n \n --scissors::\n-\tRemove everything in body before a scissors line.  A line that\n-\tmainly consists of scissors (either \">8\" or \"8<\") and perforation\n-\t(dash \"-\") marks is called a scissors line, and is used to request\n-\tthe reader to cut the message at that line.  If such a line\n+\tRemove everything in body before a scissors line (\"-- >8 --\").\n+\tThe line represents scissors and perforation marks, and is used to\n+\trequest the reader to cut the message at that line.  If that line\n \tappears in the body of the message before the patch, everything\n \tbefore it (including the scissors line itself) is ignored when\n \tthis option is used.\n-- \n2.28.0\n\n"},{"id":"406589","messageId":"20200928225108.22634-1-evan.gates@gmail.com","threadId":"54301","inReplyTo":"20200928202035.24218-1-evan.gates@gmail.com","subject":"[PATCH v3] Doc: show example scissors line","fromName":"Evan Gates","fromEmail":"evan.gates@gmail.com","sentAt":"2020-09-28T22:51:08Z","receivedAt":"2020-09-28T23:29:00Z","isPatch":true,"sender":{"key":"evan.gates@gmail.com","avatar":"https://avatars.githubusercontent.com/u/4196295?v=4"},"body":"The text tries to say the code accepts many variations that look remotely\nlike scissors and perforation marks, but gives too little detail for users\nto decide what is and what is not taken as a scissors line for themselves.\nInstead of describing the heuristics more, just spell out what will always\nbe accepted, namely \"-- >8 --\", as it would not help users to give them\nmore choices and flexibility and be \"creative\" in their scissors line.\n\nSigned-off-by: Evan Gates <evan.gates@gmail.com>\n---\nChanges in v3:\n- Reword commit message to better explain intent\n- Add \"e.g.\" to hint at other forms\n\nChanges in v2:\n- Specify exact line instead of adding text about 8 character minimum\n\n Documentation/git-mailinfo.txt | 7 +++----\n 1 file changed, 3 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt\nindex 3bbc731f67..7a6aed0e30 100644\n--- a/Documentation/git-mailinfo.txt\n+++ b/Documentation/git-mailinfo.txt\n@@ -72,10 +72,9 @@ conversion, even with this flag.\n \tis useful in order to associate commits with mailing list discussions.\n \n --scissors::\n-\tRemove everything in body before a scissors line.  A line that\n-\tmainly consists of scissors (either \">8\" or \"8<\") and perforation\n-\t(dash \"-\") marks is called a scissors line, and is used to request\n-\tthe reader to cut the message at that line.  If such a line\n+\tRemove everything in body before a scissors line (e.g. \"-- >8 --\").\n+\tThe line represents scissors and perforation marks, and is used to\n+\trequest the reader to cut the message at that line.  If that line\n \tappears in the body of the message before the patch, everything\n \tbefore it (including the scissors line itself) is ignored when\n \tthis option is used.\n-- \n2.28.0\n\n"},{"id":"406590","messageId":"xmqqpn65jzyg.fsf@gitster.c.googlers.com","threadId":"54301","inReplyTo":"20200928202035.24218-1-evan.gates@gmail.com","subject":"Re: [PATCH v2] Doc: specify exact scissors line","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-09-28T22:31:19Z","receivedAt":"2020-09-28T23:29:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Evan Gates <evan.gates@gmail.com> writes:\n\n> The existing wording covers most of the requirements of a scissors\n> line, but there is no mention of ...\n> ...\n> Specify the exact line to use (\"-- >8 --\") instead of trying to document\n> all the details.\n\ns/most/some/;\n\nFor example, the code has fun heuristics to understand that things\nlike \"-- >8 ---- >8 -- cut here -- >8 ---- >8 --\" is a scissors\nline, but we do not document it.\n\nBut what we agreed is that it is a bad idea to even attempt to\ndescribe the heuristics down to the details and sell the feature as\n\"we accept anything that resembles a perforation drawn or printed on\npaper\".  Instead we are giving less choices to make it easier for\nusers to follow, and the updated text is a move in that direction.\n\nSo selling this change based on \"the existing description does not\ngive enough\" is not good.\n\n    The text tries to say the code accepts many variations that\n    looks remotely like scissors and perforation line, but gives too\n    little detail for users to decide what is and what is not taken\n    as a scissors line for themselves.  Instead of describing the\n    heuristics more, just spell out what will always be accepted,\n    namely \"-- >8 --\", as it would not help users to give them more\n    choices and flexibility and be \"creative\" in their scissors\n    line.\n\nperhaps?\n\n> Signed-off-by: Evan Gates <evan.gates@gmail.com>\n> ---\n> Changes in v2:\n> - Specify exact line instead of adding text about 8 character minimum\n>\n>  Documentation/git-mailinfo.txt | 7 +++----\n>  1 file changed, 3 insertions(+), 4 deletions(-)\n>\n> diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt\n> index 3bbc731f67..fbb7d2813f 100644\n> --- a/Documentation/git-mailinfo.txt\n> +++ b/Documentation/git-mailinfo.txt\n> @@ -72,10 +72,9 @@ conversion, even with this flag.\n>  \tis useful in order to associate commits with mailing list discussions.\n>  \n>  --scissors::\n> +\tRemove everything in body before a scissors line (\"-- >8 --\").\n> +\tThe line represents scissors and perforation marks, and is used to\n> +\trequest the reader to cut the message at that line.  If that line\n\nWe want to say \"e.g.\", i.e. 'a scissors line (e.g. \"-- >8 --\")', in\norder to hint that we may accept other forms [*1*], and also to hint\nthat we do not want to go int details.\n\nOther than that, I like the conciseness of the updated text.\n\n\n[Footnote]\n*1* This is primarily to be friendly to left-handers to let them\nwrite \"-- 8< --\".\n"},{"id":"406593","messageId":"xmqq8sctjwoy.fsf@gitster.c.googlers.com","threadId":"54301","inReplyTo":"20200928225108.22634-1-evan.gates@gmail.com","subject":"Re: [PATCH v3] Doc: show example scissors line","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-09-28T23:41:49Z","receivedAt":"2020-09-28T23:41:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thanks.\n"}]}