Re: [PATCH v3] Introduce a description of the Backport and Fixes tags

[Julien Grall <julien@xxxxxxx>]

Hi Stefano,

On 17/04/2020 23:24, Stefano Stabellini wrote:
> Create a new document under docs/process to describe our special tags.
> Add a description of the Fixes tag and the new Backport tag. Also
> clarify that lines with tags should not be split.
>
> Signed-off-by: Stefano Stabellini <stefano.stabellini@xxxxxxxxxx>
> CC: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
> CC: Wei Liu <wl@xxxxxxx>
> CC: jbeulich@xxxxxxxx
> CC: george.dunlap@xxxxxxxxxx
> CC: julien@xxxxxxx
> CC: lars.kurth@xxxxxxxxxx
> CC: andrew.cooper3@xxxxxxxxxx
> CC: konrad.wilk@xxxxxxxxxx
> ---
> Removing Acks as I added the description of "Fixes"
> ---
>   docs/process/tags.pandoc | 55 ++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 55 insertions(+)
>   create mode 100644 docs/process/tags.pandoc
>
> diff --git a/docs/process/tags.pandoc b/docs/process/tags.pandoc
> new file mode 100644
> index 0000000000..06b06dda01
> --- /dev/null
> +++ b/docs/process/tags.pandoc
> @@ -0,0 +1,55 @@
> +Tags: No line splitting
> +-----------------------
> +Do not split a tag across multiple lines, tags are exempt from the
> +"wrap at 75 columns" rule in order to simplify parsing scripts.  For
> +example:
> +
> +        Fixes: 67d01cdb5 ("x86: infrastructure to allow converting certain indirect 
> calls to direct ones")
The SHA-1 ID is 9 characters but...

> +
> +
> +Fixes Tag
> +---------
> +
> +If your patch fixes a bug in a specific commit, e.g. you found an issue using
> +``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
> +the SHA-1 ID, and the one line summary.
... you request 12 characters here. Can you make sure the two match please?

However, I am not entirely sure why we should mandate 12 characters. 
With the title, you should always be able to find back the commit if 
there is a clash.
> +
> +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\")
> +
> +
> +Backport Tag
> +------------
> +
> +A backport tag is an optional tag in the commit message to request a
> +given commit to be backported to the stable trees:
> +
> +    Backport: 4.9+
> +
> +It marks a commit for being a candidate for backports to all stable
> +trees from 4.9 onward.
> +
> +The backport requester is expected to specify which currently supported
> +releases need the backport; but encouraged to specify a release as far
> +back as possible which applies. If the requester doesn't know the oldest
> +affected tree, they are encouraged to append a comment like the
> +following:
> +
> +    Backport: 4.9+ # maybe older
> +
> +Maintainers request the Backport tag to be added on commit. Contributors
> +are welcome to mark their patches with the Backport tag when they deem
> +appropriate. Maintainers will request for it to be removed when that is
> +not the case.
> +
> +Please note that the Backport tag is a **request** for backport, which
> +will still need to be evaluated by the stable tree maintainers.
> +Maintainers might ask the requester to help with the backporting work if
> +it is not trivial.
> +
> +When possible, please use the Fixes tag instead.
Cheers,

--
Julien Grall