README.md: Expand instructions for updating / fixing up backports

Describe how to reset backport state manually, and add to-dos to make
the UI more useful.

Also include a section on using `fixup!` commits.

While here, fix a bunch of trailing whitespace.

Signed-off-by: George Dunlap <george.dunlap@citrix.com>

diff --git a/README.md b/README.md
index 9d4375515ea25fa60eba7c55ffd1988918425c81..36bf702e7880aa7a415e6aba60f8c084c03eb36d 100644 (file)
--- a/README.md
+++ b/README.md
@@ -220,11 +220,11 @@ This command will:
 
  - Take the current value of `xen.git` `stable-${v}` for the "stable
    baseline" for each version
- 
+
  - In `xen.git`:
- 
+
    - create branches `xsa/213/xsa/${v}-{stable,baseline}`
-   
+
    - create branch `xsa/213/master`
 
 The developer now generates patch for XSA 213 on `xsa/213/master`.
@@ -233,7 +233,7 @@ The developer now generates patch for XSA 213 on `xsa/213/master`.
 
  - Starting with the latest release and going backwards, looks for
    versions such that `xsa/213/$v` doesn't exist.
- 
+
  - It will then create a branch which is a clone of `xsa/213/${v+1}`,
    and then rebase onto `xsa/213/${v}-baseline`.
 
@@ -246,6 +246,68 @@ chance to inspect and test the backport.
 The developer repeats `xsatool 213 backport` until all backports have
 been made.
 
+If the original patch is updated, to re-run the backport, the
+developer must manually delete all branches `xsa/NNN/VVV` that need to
+be re-done.
+
+**TODO** Make sure that there aren't any uncommitted changes from the
+previous backport before going forward
+
+**TODO** Add a way to reset backport state.
+
+NB an alternate way to update backports is a combination of `fixup!` commits,
+`cherry-pick`, and `rebase --autosquash`:
+
+```
+$ git commit -a --fixup 9d1a7cd4a4
+[xsa/299/master 064e86dcc4] fixup! x86/mm: Don't drop a type ref unless you held a ref to begin with
+ 1 file changed, 1 insertion(+), 4 deletions(-)
+
+$ for i in 4.12 4.11 4.10 4.9 4.8 ; do git checkout xsa/299/$i || break ; head=$(git log HEAD~.. | cut -f1 -d' '); echo $head; done
+
+Switched to branch 'xsa/299/4.12'
+[xsa/299/4.12 83c50aced4] fixup! x86/mm: Don't drop a type ref unless you held a ref to begin with
+ Date: Tue Oct 29 14:05:37 2019 +0000
+ 1 file changed, 1 insertion(+), 4 deletions(-)
+Switched to branch 'xsa/299/4.11'
+[xsa/299/4.11 0040fb1034] fixup! x86/mm: Don't drop a type ref unless you held a ref to begin with
+ Date: Tue Oct 29 14:05:37 2019 +0000
+ 1 file changed, 1 insertion(+), 4 deletions(-)
+Switched to branch 'xsa/299/4.10'
+[xsa/299/4.10 10dbfb542c] fixup! x86/mm: Don't drop a type ref unless you held a ref to begin with
+ Date: Tue Oct 29 14:05:37 2019 +0000
+ 1 file changed, 1 insertion(+), 4 deletions(-)
+Switched to branch 'xsa/299/4.9'
+[xsa/299/4.9 9eaed3cb20] fixup! x86/mm: Don't drop a type ref unless you held a ref to begin with
+ Date: Tue Oct 29 14:05:37 2019 +0000
+ 1 file changed, 1 insertion(+), 4 deletions(-)
+Switched to branch 'xsa/299/4.8'
+[xsa/299/4.8 26c6d4b33f] fixup! x86/mm: Don't drop a type ref unless you held a ref to begin with
+ Date: Tue Oct 29 14:05:37 2019 +0000
+ 1 file changed, 1 insertion(+), 4 deletions(-)
+
+$ export GIT_SEQUENCE_EDITOR=true; for i in 4.8 4.9 4.10 4.11 4.12 master ; do git checkout xsa/299/$i || break ; git rebase -i --autosquash xsa/299/$i-baseline || break ; done ; unset GIT_SEQUENCE_EDITOR
+
+Switched to branch 'xsa/299/4.8'
+hint: Waiting for your editor to close the file...
+Successfully rebased and updated refs/heads/xsa/299/4.8.
+Switched to branch 'xsa/299/4.9'
+hint: Waiting for your editor to close the file...
+Successfully rebased and updated refs/heads/xsa/299/4.9.
+Switched to branch 'xsa/299/4.10'
+hint: Waiting for your editor to close the file...
+Successfully rebased and updated refs/heads/xsa/299/4.10.
+Switched to branch 'xsa/299/4.11'
+hint: Waiting for your editor to close the file...
+Successfully rebased and updated refs/heads/xsa/299/4.11.
+Switched to branch 'xsa/299/4.12'
+hint: Waiting for your editor to close the file...
+Successfully rebased and updated refs/heads/xsa/299/4.12.
+Switched to branch 'xsa/299/master'
+hint: Waiting for your editor to close the file...
+Successfully rebased and updated refs/heads/xsa/299/master.
+```
+
 `xsatool 213 sync-patches [<versionlist>]`
 
 For each version for which `xsa/213/${v}` exists, this will:
@@ -255,12 +317,12 @@ For each version for which `xsa/213/${v}` exists, this will:
  - Generate patches in xsa.git
 
  - Update the recipe for that version in `xsa213.meta`
- 
+
 If `<versionlist>` is supplied, it will be limited to the range
 specified.
- 
+
 `xsatool 213 dedup-patches`
- 
+
 Sync-patches will always generate a separate set of patches for each
 version.  But it's often the case that a single patch or set of
 patches can apply to multiple versions.
@@ -271,15 +333,15 @@ equivalent to those in the next higher version:
 
  - Create a branch called `xsa/dedup-canonical` using the current
    recipe for version `${v}`
-   
+
  - Attempt to create a branch called `xsa/dedup-candidate` using the
    recipe for version `${v}+1`.  If the `git am` fails, the current
    patches are not redundant and move on to the next version.
-   
+
  - Compare a hash of the two trees (generated with `git rev-partse
    $branch:`).  If they match, replace the recipe `${v}` with the
    recipe for `${v}+1`.  Otherwise, leave it as it is.
-   
+
 NB at the moment this only works for the xen repo.
 
 ## Creating XSA metadata from existing patches
@@ -412,7 +474,7 @@ doing a rebase), failing out in case of an error. If no
 ## Marking XSAs as published
 
 To mark an XSA as published (i.e., to remove XSAs from the list of
-"default prerequisites" for new XSAs), edit `global.meta` and 
+"default prerequisites" for new XSAs), edit `global.meta` and
 
 ## Adding a new Xen release to support
 
@@ -446,7 +508,7 @@ to reformat a file according to Golang's default format.  This will:
   - Sort versions in SupportedVersions in decending order (xsatool canon).
   - Remove unknown or obsolete elements.  NB this includes the "XenVersion"
     element in older recipes.
-       
+
 For convenience, the British spelling ("canonicalise") is also accepted.
 
 # Potential future functionality
@@ -475,7 +537,7 @@ applied to stable branches.
 
 ## Generating osstest test runes automatically
 
-## Rebasing 
+## Rebasing
 
 - Rebasing to new versions of `stable` or `master`
 
@@ -524,4 +586,3 @@ it ever be the case that xsa 251, for xen.git, depends on xsa250,
 which contains both xen.git and qemu-upstream.git components?  If so
 then when testing xsa251 we'd have to make sure that *all* the trees
 were in the appropriate state.
-