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@xilinx.com>
Acked-by: Wei Liu <wl@xen.org>
CC: Ian Jackson <ian.jackson@eu.citrix.com>
CC: jbeulich@suse.com
CC: george.dunlap@citrix.com
CC: julien@xen.org
CC: lars.kurth@citrix.com
CC: andrew.cooper3@citrix.com
CC: konrad.wilk@oracle.com

---

Changes in v4:
- fix example
- use released trees instead of stable trees
- add (or in addition)

---
 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..1841cb87a8
--- /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: 67d01cdb5518 ("x86: infrastructure to allow converting certain indirect calls to direct ones")
+
+
+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.
+
+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 released trees:
+
+    Backport: 4.9+
+
+It marks a commit for being a candidate for backports to all released
+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 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 (or in addition).
-- 
2.17.1

Stefano Stabellini writes ("[PATCH] Introduce a description of the Backport and Fixes tags"):
> 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@xilinx.com>
> Acked-by: Wei Liu <wl@xen.org>

Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

> +When possible, please use the Fixes tag instead (or in addition).

Do we have any code to turn Fixes: into a list of commits to
backport to a particular stable branch ?

If not it might be easier to ask people to add both Backport: and
Fixes:.

Ian.

On Tue, Apr 21, 2020 at 07:49:15PM +0100, Ian Jackson wrote:
> Stefano Stabellini writes ("[PATCH] Introduce a description of the Backport and Fixes tags"):
> > 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@xilinx.com>
> > Acked-by: Wei Liu <wl@xen.org>
> 
> Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
> 
> > +When possible, please use the Fixes tag instead (or in addition).
> 
> Do we have any code to turn Fixes: into a list of commits to
> backport to a particular stable branch ?

I think we should have one of those, I've attempted something like:

#!/bin/sh -e

branch=$1
remote=$2

for fix in `git log ${remote}/master --grep='^Fixes:\s.*' --format="%H"`; do
    # Check if the fix is already part of the branch, in which case we have
    # gone backwards enough
    if git branch --contains $fix -r | \
       grep -q ${remote}/staging-${branch}; then
        break;
    fi
    bug=`git show $fix | grep -E '^\s*Fixes:\s.*' | awk '{ print $2 }'`
    # Append possible backports of the bug
    bugs="$bug `git log --grep="^master commit: $bug" --format="%H" --all` \
               `git log --grep="^(cherry picked from commit $bug" --format="%H" --all`"
    for bug in $bugs; do
        if ! git branch --contains $bug -r | \
             grep -q ${remote}/staging-${branch}; then
            continue
        fi
        # Check if fix has been backported
        fixes="`git log --grep="^master commit: $fix" --format="%H" --all` \
               `git log --grep="^(cherry picked from commit $fix" --format="%H" --all`"
        fixed=0
        for f in $fixes; do
            if git branch --contains $f -r | \
               grep -q ${remote}/staging-${branch}; then
                fixed=1
                break
            fi
        done
        if [ $fixed == 0 ]; then
            echo "$fix"
            break
        fi
    done
done

But it's hard to actually test whether it's correct. Seems to produce
some output, but I'm not sure whether it's missing commits, use as:

# ./check-branch.sh 4.12 origin

The script could also likely be cleaned up and improved, it's quite
ugly...

> If not it might be easier to ask people to add both Backport: and
> Fixes:.

I would like to avoid that, a Fixes tag should be enough for us to
figure out where the patch should be applied.

Thanks, Roger.

Roger Pau Monne writes ("Re: [PATCH] Introduce a description of the Backport and Fixes tags"):
> On Tue, Apr 21, 2020 at 07:49:15PM +0100, Ian Jackson wrote:
> > Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
> > 
> > > +When possible, please use the Fixes tag instead (or in addition).
> > 
> > Do we have any code to turn Fixes: into a list of commits to
> > backport to a particular stable branch ?
> 
> I think we should have one of those, I've attempted something like:

Cool :-).

> > If not it might be easier to ask people to add both Backport: and
> > Fixes:.
> 
> I would like to avoid that, a Fixes tag should be enough for us to
> figure out where the patch should be applied.

OK.  Let us start using these tags as defined in Stefano's patch and
we can debug the script when we have some test data :-).

> #!/bin/sh -e

I tried to avoid reading your script but I couldn't help glancing at
the first line and

  #!/bin/sh
  set -e

is better because then

  bash -x script

isn't a bomb.

> The script could also likely be cleaned up and improved, it's quite
> ugly...

We can put it in-tree and then people can send patches...

Ian.