Subject: [bug#57598] [PATCH] doc: Update contribution guidelines on patches, etc.

From: Kyle Meyer <[email-masked]>
Date: Sun, 25 Sep 2022 14:58:50 -0400

Maxime Devos writes:

> On 24-09-2022 15:03, Ludovic Courtès wrote:
[...]
>> You can write comments below the --- and diffstats.  That way, ‘git am’
>> will ignore them when applying the patch.
>
> I know of '---', but AFAICT this is undocumented behaviour, so I'm 
> hesitant to rely on that.

I don't think you should be worried about Git changing that behavior.
It's used heavily by the Git project itself as well as many other
projects.

Here are some mentions in git.git (4fd6c5e444):

,----[ Documentation/SubmittingPatches ]
| 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 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`.
`----

,----[ Documentation/git-notes.txt ]
| Notes can also be added to patches prepared with `git format-patch` by
| using the `--notes` option. Such notes are added as a patch commentary
| after a three dash separator line.
`----

,----[ Documentation/user-manual.txt ]
| `git format-patch` can include an initial "cover letter". You can insert
| commentary on individual patches after the three dash line which
| `format-patch` places after the commit message but before the patch
| itself.  If you use `git notes` to track your cover letter material,
| `git format-patch --notes` will include the commit's notes in a similar
| manner.
`----

,----[ Documentation/git-format-patch.txt ]
| Typically it will be placed in a MUA's drafts folder, edited to add
| timely commentary that should not go in the changelog after the three
| dashes, and then sent as a message whose body, in our example, starts
| with "arch/arm config files were...".  On the receiving end, readers [...]
`----