Re: [PATCH v2] docs: document patch rules

[Juergen Gross <jgross@xxxxxxxx>]

On 04.02.22 20:25, Julien Grall wrote:
> Hi,
>
> On 03/02/2022 12:54, Juergen Gross wrote:
> > +## The commit message
> > +
> > +The commit message is free text describing *why* the patch is done and
> > +*how* the goal of the patch is achieved. A good commit message will 
> > describe
> > +the current situation, the desired goal, and the way this goal is being
> > +achieved. Parts of that can be omitted in obvious cases.
> > +
> > +In case additional changes are done in the patch (like e.g. 
> > cleanups), those
> > +should be mentioned.
> > +
> > +When referencing other patches (e.g. `similar to patch xy ...`) those
> > +patches should be referenced via their commit id (at least 12 digits)
> > +and the patch subject, if the very same patch isn't referenced by the
> > +`Fixes:` tag, too:
> > +
> > +    Similar to commit 67d01cdb5518 ("x86: infrastructure to allow 
> > converting
> > +    certain indirect calls to direct ones") add ...
> > +
> > +The following ``git config`` settings can be used to add a pretty 
> > format for
> > +outputting the above style in the ``git log`` or ``git show`` commands:
> > +
> > +        [core]
> > +                abbrev = 12
> > +        [pretty]
> > +                fixes = Fixes: %h (\"%s\")
> > +
> > +Lines in the commit message should not exceed 75 characters, except when
> I was under the impression that commit message should be wrap to 72 
> characters. This is because tools like "git log" would indent the commit 
> message by 8 characters.
I took that value from the docs/process/tags.pandoc file.

BTW, git log is indenting the commit message by 4 characters on my
system.

> > +copying error output directly into the commit message.
> > +
> > +## Tags
> > +
> > +Tags are entries in the form
> > +
> > +    Tag: something
> > +
> > +In general tags are added in chronological order. So a `Reviewed-by:` 
> > tag
> > +should be added **after** the `Signed-off-by:` tag, as the review 
> > happened
> > +after the patch was written.
> > +
> > +Do not split a tag across multiple lines, tags are exempt from the
> > +"wrap at 75 columns" rule in order to simplify parsing scripts.
> This would need to be adjusted depending on the answer above.
>
> > +
> > +### Origin:
> > +
> > +Xen has inherited some source files from other open source projects. 
> > In case
> > +a patch modifying such an inherited file is taken from that project 
> > (maybe in
> > +modified form), the `Origin:` tag specifies the source of the patch:
> > +
> > +    Origin: <repository-URL> <commit-id>
> NIT: Likes you did for Fixes tags, can you make clear that the commit id 
> should be the first 12 characters? So the line...
Okay.


Juergen

Attachment: OpenPGP_0xB0DE9DD628BF132F.asc
Description: OpenPGP public key

Attachment: OpenPGP_signature
Description: OpenPGP digital signature