xsatool: Update README.md with more complete usage information

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

diff --git a/README.md b/README.md
index 64a9c33080b34607de2b8b81b724d6ca6cfe9c1a..0ae2b685b5eaee1c7b4c1b6f3fa20d29a2a32337 100644 (file)
--- a/README.md
+++ b/README.md
@@ -52,8 +52,7 @@ allow the release in a nice clean order.)
 
 It should probably be obvious that creating this XSA 'recipe' (as
 opposed to allocating the XSA number) shouldn't be done until a patch
-is reasonably close to being ready; XSA-115 provides a good reason
-why.
+is reasonably close to being ready.
 
 The actual creation and manipulation of the patches will be highly
 context-dependent and developer-driven; to that end the standard will
@@ -66,10 +65,8 @@ commands to 'sync' between the trees.
 ## .xsatool
 
 xsatool expects a top-level directory that contains a file named
-`.xsatool`.  This configuration file contains paths for xen,
-qemu-upstream, qemu-traditional, and xsa.git.  `xsatool` will
-manipulate these working trees freely, so it is highly advised that
-these trees be separate from normal development trees.
+`.xsatool`.  This configuration file contains paths for working
+repositories for xen, qemu-upstream, qemu-traditional, and xsa.git.
 
 ## xsa.git/global.meta
 
@@ -98,21 +95,46 @@ is formatted; I've tried to format the structures such that they have
 reasonable-looking JSON output which can be edited by hand without too
 much effort if need be.
 
-# Trees
+# Working repositories and branches
+
+## Overview
+
+The developer-oriented functionality of xsatool needs access to xen,
+qemu-traditional, and qemu-upstream repositories in order to test and
+create patches.
+
+By default `xsatool` will make its own copies, so that it knows where
+they are and it doesn't have to worry about interrupting a developer's
+other workflows.  You can, however, specify a path to existing
+repositories instead.  Be aware that `xsatool` may have any of the following
+effects on the tree:
+
+- Modify the working tree (including git clean -ffdx)
+
+- Modify HEAD
+
+- Create, delete, or modify branches matching `xsa/*`
+
+**FIXME** Need to move test branches under xsa
+
+- "Fetch" from master and stable-* branches
 
 ## Branch names
 
-When an "empty" XSA is created, two three will be created in each tree
-for which patches are required:
+Branches for an XSA are named by the following pattern:
 
     xsa/${n}/${v}-stable
     xsa/${n}/${v}-baseline
     xsa/${n}/${v}
 
-`${v}` is the major release version.  The `-stable` branch points to
-the commit in the `stable-${v}` tree at the point at which the xsa was
-created.  `baseline` is `stable` with all of the prerequisite XSAs
-applied.  The last branch is the branch that contains the actual fix.
+`${n}` is the XSA number, and `${v}` is the major release version.
+The `-stable` branch points to the commit in the `stable-${v}` tree at
+the point at which the xsa was created.  `baseline` is `stable` with
+all of the prerequisite XSAs applied.  The last branch is the branch
+that contains the actual fix.
+
+Other branches may be made as a part of operations, but will always have the
+`xsa/` prefix (e.g., `xsa/tmp`).
 
 ## Generating patches from a branch
 
@@ -154,7 +176,7 @@ rerere.enabled true`.)
 The `--mirrordir` or `--git-proxy` arguments can be used to specify a
 cache used for git clones *during build*.
 
-## Creating or updating the initial global metadata
+## Creating the initial global metadata
 
 `xsatool global update`
 
@@ -164,17 +186,22 @@ It then goes through `xen.git` and looks for `RELEASE-M.m.p` tags, and
 marks each version greater than or equal to the specified version as
 supported.
 
-If `global.meta` does exist, it simply does a refresh; this will
-automatically add support for new versions.
-
 # Workflow
 
-## New Xen XSA
+## Generating a new XSA
 
 Using XSA 213 as an example.
 
+Make sure your master and stable-* branches are up to date:
+
+`xsatool repo update`
+
+Initialize the new XSA
+
 `xsatool 213 init xen`
 
+This command will:
+
  - Create `xsa213.meta` with "empty" recipes for master and all
    currently-supported versions; in this case these versions will
    probably be `master`, `4.8`, `4.7`, `4.6`, and `4.5`.  Tell
@@ -210,7 +237,7 @@ been made.
 
 `xsatool 213 sync-patches`
 
-For each version fro which `xsa/213/${v}` exists, this will:
+For each version for which `xsa/213/${v}` exists, this will:
 
  - Delete any patches in xsa.git which match its file generation pattern.
 
@@ -218,6 +245,53 @@ For each version fro which `xsa/213/${v}` exists, this will:
 
  - Update the recipe for that version in `xsa213.meta`
 
+## Creating XSA metadata from existing patches
+
+For example, if the patches were made by a colleague.
+
+Make sure your master and stable-* branches are up to date:
+
+`xsatool repo update`
+
+Using XSA 228 as an example
+
+`xsatool 228 init xen`
+
+This creates an 'empty' xsa228.meta file, and the appropriate
+`-stable` and `-baseline` branches.
+
+Now edit `xsa228.meta`.  Under "Recipes", for each Xen version, there
+will be an entry called "Patches" that will be an empty array (`[ ]`).  
+Add the name of the appropriate patch in quotes inside the brackets
+for each Xen version.
+
+In the case of XSA 228, you'd enter `"xsa228.patch"` under both
+`"master"` and `"4.9"`, `"xsa228-4.8.patch"` under `"4.8"`, `"4.7"`,
+`"4.6"`, and so on.
+
+**TODO**
+
+Implement a command to do this; for example:
+
+`xsatool 228 set-patches 4.9 xsa228.patch`
+
+## Excluding a particular Xen version from an XSA
+
+Sometimes one of the currently-supported Xen versions isn't vulnerable
+to a particular XSA.  In that case, run the `xsatool init` command as
+above, then manually edit the resulting metadata file and remove the
+stanza for the version of Xen which doesn't need the XSA.
+
+**TODO**
+
+Implement a command to do this; for example:
+
+`xsatool 228 exclude 4.5`
+
+or:
+
+`xsatool 228 init --exclude=4.5 xen`
+
 ## Checking patches before sending them out
 
 `xsatool 213 test-apply`
@@ -279,6 +353,29 @@ value of the 'stable' branch (either `master` or `stable-VV`).  It
 will then re-apply the patch and any prerequisites as-is (i.e., *not*
 doing a rebase), failing out in case of an error.
 
+## 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 
+
+## Adding a new Xen release to support
+
+`xsatool global update`
+
+Assuming `global.meta` exists, this will automatically add support for
+new versions.
+
+Alternately, the `global.meta` file can be modified directly by
+copying an existing version 'stanza' and modifying the version number.
+
+## Removing a Xen version from support
+
+Edit the `global.meta` file and remove the stanza for the version no
+longer supported.
+
+(Eventually this will be implemented by the `xsatool global
+end-support [version]` command.)
+
 # Potential future functionality
 
 ## Automatically de-duplicating patches
@@ -288,6 +385,12 @@ for each supported version, even if a single patch can apply to
 multiple versions.  Detecting this automatically would be one of the
 obvious next steps.
 
+`git rev-parse {rev}:` will give you the hash of the contents of the
+tree at revision `{rev}`.  To see if a patch for version V is
+necessary, you should be able to try applying the patch verion V+1 to
+a temporary branch.  If it applies, and the tree hash is the same, you
+can use V+1 instead of making a patch for V.
+
 ## Removing xsas from the 'outstanding' list
 
 Either something like:
@@ -333,6 +436,12 @@ Developer checks out xsa/213/master, makes a fix, and commits it using git commi
 
 `xsatool global info`
 
+## Exposing potentially useful lower-level functionality
+
+For example, if we had the functionality to check if a patch is appled:
+
+`xsatool cmd patch-is-applied xen.git staging-4.8 $commithash xsa231.patch`
+
 # Open issues
 
 # Inter-tree dependcies