From: Junio C Hamano Date: Mon, 22 Dec 2014 17:55:41 GMT Subject: Re: [PATCH 1/2] Documentation/SubmittingPatches: Explain the rationale of git notes Message-ID: 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.