# [PATCH 1/2] Documentation/SubmittingPatches: Explain the rationale of git notes 10 messages from 2014-12-18 to 2014-12-30. Participants: Stefan Beller, Junio C Hamano, Eric Sunshine. Thread: https://gitlist.dev/t/38193 ## Stefan Beller, 2014-12-18 01:08 Subject: [PATCH 1/2] Documentation/SubmittingPatches: Explain the rationale of git notes Message-ID: <1418864895-18583-1-git-send-email-sbeller@google.com> URL: https://gitlist.dev/e/1418864895-18583-1-git-send-email-sbeller%40google.com In-Reply-To: ``` This adds an explanation of why you want to have the --notes option given to git format-patch. Signed-off-by: Stefan Beller --- Notes: > with optionally update Documentation/SubmittingPatches > to point at the file. That file actually talks about notes already. I am sending two patches touching that file, one of them explaining the --notes workflow rationale and one of them just changing white spaces. A few weeks ago I wanted to patch format-patch to remove change ids. This is not needed any more for the git workflow as I disabled them and do not upload any patches to an optional Gerrit code review server anymore. I do like the workflow using --notes as well from a developers perspective as I take literally notes for my own sanity. I wonder if I should add a config format.notes = [default-off, always, on-if-non-empty] so I don't need always add --notes manually to the command line. Thanks, Stefan Documentation/SubmittingPatches | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index fa71b5f..16b5d65 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -176,7 +176,11 @@ message starts, you can put a "From: " line to name that person. You often want to add additional explanation about the patch, other than the commit message itself. Place such "cover letter" material between the three dash lines and the diffstat. Git-notes -can also be inserted using the `--notes` option. +can also be inserted using the `--notes` option. If you are one +of those developers who cannot write perfect code the first time +and need multiple iterations of review and discussion, you are +encouraged to use the notes to describe the changes between the +different versions of a patch. Do not attach the patch as a MIME attachment, compressed or not. Do not let your e-mail client send quoted-printable. Do not let -- 2.2.0.31.gad78000.dirty ``` ## Stefan Beller, 2014-12-18 01:08 Subject: [PATCH] Documentation/SubmittingPatches: unify whitespace/tabs for the DCO Message-ID: <1418864895-18583-2-git-send-email-sbeller@google.com> URL: https://gitlist.dev/e/1418864895-18583-2-git-send-email-sbeller%40google.com In-Reply-To: <1418864895-18583-1-git-send-email-sbeller@google.com> ``` The Developers Certificate of Origin has a mixture of tabs and white spaces which is annoying to view if your editor explicitly views white space characters. Signed-off-by: Stefan Beller --- Documentation/SubmittingPatches | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 16b5d65..6124f34 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -258,15 +258,15 @@ pretty simple: if you can certify the below: person who certified (a), (b) or (c) and I have not modified it. - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. then you just add a line saying - Signed-off-by: Random J Developer + Signed-off-by: Random J Developer This line can be automatically added by Git if you run the git-commit command with the -s option. -- 2.2.0.31.gad78000.dirty ``` ## Stefan Beller, 2014-12-18 01:08 Subject: [PATCH 2/2] Documentation/SubmittingPatches: unify whitespace/tabs for the DCO Message-ID: <1418864895-18583-3-git-send-email-sbeller@google.com> URL: https://gitlist.dev/e/1418864895-18583-3-git-send-email-sbeller%40google.com In-Reply-To: <1418864895-18583-1-git-send-email-sbeller@google.com> ``` The Developers Certificate of Origin has a mixture of tabs and white spaces which is annoying to view if your editor explicitly views white space characters. Signed-off-by: Stefan Beller --- Notes: I'll also try to send it upstream to linux. Documentation/SubmittingPatches | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 16b5d65..6124f34 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -258,15 +258,15 @@ pretty simple: if you can certify the below: person who certified (a), (b) or (c) and I have not modified it. - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. then you just add a line saying - Signed-off-by: Random J Developer + Signed-off-by: Random J Developer This line can be automatically added by Git if you run the git-commit command with the -s option. -- 2.2.0.31.gad78000.dirty ``` ## Junio C Hamano, 2014-12-22 17:55 Subject: Re: [PATCH 1/2] Documentation/SubmittingPatches: Explain the rationale of git notes Message-ID: URL: https://gitlist.dev/e/xmqqwq5ja7s2.fsf%40gitster.dls.corp.google.com In-Reply-To: <1418864895-18583-1-git-send-email-sbeller@google.com> ``` Stefan Beller writes: > This adds an explanation of why you want to have the --notes option > given to git format-patch. > > Signed-off-by: Stefan Beller > --- > > Notes: > > with optionally update Documentation/SubmittingPatches > > to point at the file. > > That file actually talks about notes already. I am sending > two patches touching that file, one of them explaining > the --notes workflow rationale and one of them just changing > white spaces. > > A few weeks ago I wanted to patch format-patch to remove > change ids. This is not needed any more for the git workflow > as I disabled them and do not upload any patches to an optional > Gerrit code review server anymore. > > I do like the workflow using --notes as well from a developers > perspective as I take literally notes for my own sanity. > I wonder if I should add a config format.notes = [default-off, > always, on-if-non-empty] so I don't need always add --notes > manually to the command line. > > Thanks, > Stefan > > Documentation/SubmittingPatches | 6 +++++- > 1 file changed, 5 insertions(+), 1 deletion(-) > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index fa71b5f..16b5d65 100644 > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -176,7 +176,11 @@ message starts, you can put a "From: " line to name that person. > You often want to add additional explanation about the patch, > other than the commit message itself. Place such "cover letter" > material between the three dash lines and the diffstat. Git-notes > -can also be inserted using the `--notes` option. > +can also be inserted using the `--notes` option. If you are one Because the previous sentence is talking about the cover letter to describe the overall series, it probably is a good idea to add "after the three-dashes of each patch" after "... using the notes option" for clarity, perhaps? > +of those developers who cannot write perfect code the first time > +and need multiple iterations of review and discussion, you are > +encouraged to use the notes to describe the changes between the > +different versions of a patch. Perhaps s/you are encouraged to/you may want to/? It might be better to be even more explicit, e.g. "you may want to keep track of the changes between the versions using the notes and then use `--notes` when preparing the series for submission"? > Do not attach the patch as a MIME attachment, compressed or not. > Do not let your e-mail client send quoted-printable. Do not let Thanks. ``` ## Junio C Hamano, 2014-12-22 17:55 Subject: Re: [PATCH 2/2] Documentation/SubmittingPatches: unify whitespace/tabs for the DCO Message-ID: URL: https://gitlist.dev/e/xmqqsig7a7rk.fsf%40gitster.dls.corp.google.com In-Reply-To: <1418864895-18583-3-git-send-email-sbeller@google.com> ``` Stefan Beller writes: > The Developers Certificate of Origin has a mixture of tabs and white > spaces which is annoying to view if your editor explicitly views white > space characters. > > Signed-off-by: Stefan Beller > --- > > Notes: > I'll also try to send it upstream to linux. Thanks. > > Documentation/SubmittingPatches | 12 ++++++------ > 1 file changed, 6 insertions(+), 6 deletions(-) > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index 16b5d65..6124f34 100644 > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -258,15 +258,15 @@ pretty simple: if you can certify the below: > person who certified (a), (b) or (c) and I have not modified > it. > > - (d) I understand and agree that this project and the contribution > - are public and that a record of the contribution (including all > - personal information I submit with it, including my sign-off) is > - maintained indefinitely and may be redistributed consistent with > - this project or the open source license(s) involved. > + (d) I understand and agree that this project and the contribution > + are public and that a record of the contribution (including all > + personal information I submit with it, including my sign-off) is > + maintained indefinitely and may be redistributed consistent with > + this project or the open source license(s) involved. > > then you just add a line saying > > - Signed-off-by: Random J Developer > + Signed-off-by: Random J Developer > > This line can be automatically added by Git if you run the git-commit > command with the -s option. ``` ## Stefan Beller, 2014-12-29 17:36 Subject: Re: [PATCH 1/2] Documentation/SubmittingPatches: Explain the rationale of git notes Message-ID: URL: https://gitlist.dev/e/CAGZ79kYuivGwayvJ%2BD8vOBP4yHN64Cx6UdxrSn430GyJ3K6ywg%40mail.gmail.com In-Reply-To: ``` On Mon, Dec 22, 2014 at 9:55 AM, Junio C Hamano wrote: > Stefan Beller writes: > >> This adds an explanation of why you want to have the --notes option >> given to git format-patch. >> >> Signed-off-by: Stefan Beller >> --- >> >> Notes: >> > with optionally update Documentation/SubmittingPatches >> > to point at the file. >> >> That file actually talks about notes already. I am sending >> two patches touching that file, one of them explaining >> the --notes workflow rationale and one of them just changing >> white spaces. >> >> A few weeks ago I wanted to patch format-patch to remove >> change ids. This is not needed any more for the git workflow >> as I disabled them and do not upload any patches to an optional >> Gerrit code review server anymore. >> >> I do like the workflow using --notes as well from a developers >> perspective as I take literally notes for my own sanity. >> I wonder if I should add a config format.notes = [default-off, >> always, on-if-non-empty] so I don't need always add --notes >> manually to the command line. >> >> Thanks, >> Stefan >> >> Documentation/SubmittingPatches | 6 +++++- >> 1 file changed, 5 insertions(+), 1 deletion(-) >> >> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches >> index fa71b5f..16b5d65 100644 >> --- a/Documentation/SubmittingPatches >> +++ b/Documentation/SubmittingPatches >> @@ -176,7 +176,11 @@ message starts, you can put a "From: " line to name that person. >> You often want to add additional explanation about the patch, >> other than the commit message itself. Place such "cover letter" >> material between the three dash lines and the diffstat. Git-notes >> -can also be inserted using the `--notes` option. >> +can also be inserted using the `--notes` option. If you are one > > Because the previous sentence is talking about the cover letter to > describe the overall series, it probably is a good idea to add > "after the three-dashes of each patch" after "... using the notes > option" for clarity, perhaps? The previous sentence is talking about additional information, which should not go into the commit message. (very similar to the cover letter but just for one patch). It already mentions the place "between the three dash lines and the diffstat." > >> +of those developers who cannot write perfect code the first time >> +and need multiple iterations of review and discussion, you are >> +encouraged to use the notes to describe the changes between the >> +different versions of a patch. > > Perhaps s/you are encouraged to/you may want to/? It might be > better to be even more explicit, e.g. "you may want to keep track of > the changes between the versions using the notes and then use > `--notes` when preparing the series for submission"? I did reword it to make it more obvious. > >> Do not attach the patch as a MIME attachment, compressed or not. >> Do not let your e-mail client send quoted-printable. Do not let > > Thanks. A paragraph before that change we have "git format-patch" command follows the best current practice to format the body of an e-mail message. which makes me wonder if the notes are a best practice or may be becoming a best practice. So maybe we want to default to add the notes in format-patch instead of explicitly asking for it. But that's just an idea suited for another patch. Thanks ``` ## Stefan Beller, 2014-12-29 17:42 Subject: [PATCHv2] Documentation/SubmittingPatches: Explain the rationale of git notes Message-ID: <1419874942-9901-1-git-send-email-sbeller@google.com> URL: https://gitlist.dev/e/1419874942-9901-1-git-send-email-sbeller%40google.com In-Reply-To: ``` This adds more explanation of why you want to have the --notes option given to git format-patch. Signed-off-by: Stefan Beller --- Notes: Changes v2: * s/you are encouraged to/you may want to/ * a stronger hint to use the git notes and then --notes for format-patch. Documentation/SubmittingPatches | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index e3c942e..f42c607 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -177,7 +177,12 @@ message starts, you can put a "From: " line to name that person. You often want to add additional explanation about the patch, other than the commit message itself. Place such "cover letter" material between the three dash lines and the diffstat. Git-notes -can also be inserted using the `--notes` option. +can also be inserted using the `--notes` option. If you are one +of those developers who cannot write perfect code the first time +and need multiple iterations of review and discussion, you may +want to keep track of the changes between different versions of +a patch using notes and then also use the `--notes` option when +preparing the patch for submission. Do not attach the patch as a MIME attachment, compressed or not. Do not let your e-mail client send quoted-printable. Do not let -- 2.2.1.62.g3f15098 ``` ## Eric Sunshine, 2014-12-29 23:18 Subject: Re: [PATCHv2] Documentation/SubmittingPatches: Explain the rationale of git notes Message-ID: URL: https://gitlist.dev/e/CAPig%2BcQgG5Ua-k1D8yKF5K%2BtfXeSB_wTN9W3m08F%2BK7AtKWDaw%40mail.gmail.com In-Reply-To: <1419874942-9901-1-git-send-email-sbeller@google.com> ``` On Mon, Dec 29, 2014 at 12:42 PM, Stefan Beller wrote: > This adds more explanation of why you want to have the --notes option > given to git format-patch. > > Signed-off-by: Stefan Beller > --- > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index e3c942e..f42c607 100644 > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -177,7 +177,12 @@ message starts, you can put a "From: " line to name that person. > You often want to add additional explanation about the patch, > other than the commit message itself. Place such "cover letter" > material between the three dash lines and the diffstat. Git-notes > -can also be inserted using the `--notes` option. > +can also be inserted using the `--notes` option. If you are one > +of those developers who cannot write perfect code the first time > +and need multiple iterations of review and discussion, you may > +want to keep track of the changes between different versions of > +a patch using notes and then also use the `--notes` option when > +preparing the patch for submission. Perhaps this could be rephrased in a less derogatory fashion like this: ...material between the three dash line and the diffstat. For patches requiring multiple iterations of review and discussion, an explanation of changes between each iteration can be kept in Git-notes and inserted automatically following the three dash line via `git format-patch --notes`. > Do not attach the patch as a MIME attachment, compressed or not. > Do not let your e-mail client send quoted-printable. Do not let > -- > 2.2.1.62.g3f15098 ``` ## Stefan Beller, 2014-12-29 23:21 Subject: Re: [PATCHv2] Documentation/SubmittingPatches: Explain the rationale of git notes Message-ID: URL: https://gitlist.dev/e/CAGZ79kZxsWZRdaQ-0_9Ou3y0KOruD0WVrC0Drkjgu%3DTbgUjiSA%40mail.gmail.com In-Reply-To: ``` On Mon, Dec 29, 2014 at 3:18 PM, Eric Sunshine wrote: > On Mon, Dec 29, 2014 at 12:42 PM, Stefan Beller wrote: >> This adds more explanation of why you want to have the --notes option >> given to git format-patch. >> >> Signed-off-by: Stefan Beller >> --- >> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches >> index e3c942e..f42c607 100644 >> --- a/Documentation/SubmittingPatches >> +++ b/Documentation/SubmittingPatches >> @@ -177,7 +177,12 @@ message starts, you can put a "From: " line to name that person. >> You often want to add additional explanation about the patch, >> other than the commit message itself. Place such "cover letter" >> material between the three dash lines and the diffstat. Git-notes >> -can also be inserted using the `--notes` option. >> +can also be inserted using the `--notes` option. If you are one >> +of those developers who cannot write perfect code the first time >> +and need multiple iterations of review and discussion, you may >> +want to keep track of the changes between different versions of >> +a patch using notes and then also use the `--notes` option when >> +preparing the patch for submission. > > Perhaps this could be rephrased in a less derogatory fashion like this: This wasn't meant to be derogatory at all. It was more of subtle humor. Sorry for the confusion. If this is offensive in any way I'd rather go with your suggestion indeed. > > ...material between the three dash line and the diffstat. > For patches requiring multiple iterations of review and > discussion, an explanation of changes between each iteration can > be kept in Git-notes and inserted automatically following the > three dash line via `git format-patch --notes`. > >> Do not attach the patch as a MIME attachment, compressed or not. >> Do not let your e-mail client send quoted-printable. Do not let >> -- >> 2.2.1.62.g3f15098 ``` ## Junio C Hamano, 2014-12-30 16:19 Subject: Re: [PATCHv2] Documentation/SubmittingPatches: Explain the rationale of git notes Message-ID: URL: https://gitlist.dev/e/xmqqzja5rtyf.fsf%40gitster.dls.corp.google.com In-Reply-To: ``` Stefan Beller writes: >>> +can also be inserted using the `--notes` option. If you are one >>> +of those developers who cannot write perfect code the first time >>> +and need multiple iterations of review and discussion, you may >>> +want to keep track of the changes between different versions of >>> +a patch using notes and then also use the `--notes` option when >>> +preparing the patch for submission. >> >> Perhaps this could be rephrased in a less derogatory fashion like this: > > This wasn't meant to be derogatory at all. It was more of subtle humor. > Sorry for the confusion. > > If this is offensive in any way I'd rather go with your suggestion indeed. I too found it very close to the borderline between being funny and being unnecessarily condescending when I first read it and couldn't tell which side of the line it was on. It is not if the readers need multiple iterations to get things perfect (most of us do, anyway). It is if the readers already have a good procedure to manage the changes (if they do, they do not need us to making suggestion to use notes) or they are actively in search of a good tool to add to their toolbox. From that point of view, Eric's rewrite does present a useful tool to keep track of changes that the readers may want to consider in a lot tamer way. ```