Re: [PATCH v2] docs: document patch rules

[Julien Grall <julien@xxxxxxx>]

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.
> +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...
> +
> +E.g.:
> +
> +    Origin: git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 
> f093b08c47b3
... doesn't get horribly long.

> +
> +All tags **above** the `Origin:` tag are from the original patch (which
> +should all be kept), while tags **after** `Origin:` are related to the
> +normal Xen patch process as described here.
Cheers,

--
Julien Grall