README: Do not recommend cs-flight-create

This is not a normal way to carry on.  Far too much like hard work.
Recommend make-flight or cs-adjust-flight new: instead.

CC: Julien Grall <julien.grall@arm.com>
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>

diff --git a/README b/README
index 93129e3459debda24e91b2847aea48c03ddddc58..9d97c612771778978380758fe387f8c33c56c3c8 100644 (file)
--- a/README
+++ b/README
@@ -680,39 +680,23 @@ operation.
 However it can be useful to create a custom flight "by-hand" in order
 to repeatedly test one aspect or to facilitate adhoc tests etc.
 
-A fresh empty flight is created by using the "cs-flight-create"
-script. It takes as arguments a "blessing" and a "branch" and on
-success prints the new flight number.
+The usual way to do this is to use cs-adjust-flight.  This utility can
+create completely new flights using existing ones as templates, as
+well as "edit" existing ones.
 
-The blessing should almost always be "play". The branch doesn't
-really matter, if you are testing something related to a failure on a
-given branch you may as well use that, otherwise "play" or
-"xen-unstable" is a reasonably fallback.
+If you wanted to simply copy a single job from an existing flight, you
+could do something like this:
 
-Thus the normal way to invoke cs-flight-create is:
+    $ ./cs-adjust-flight new:play copy-jobs $template <job-name> \
+                  runvar-build-set . . . "$template."
 
-    $ flight=`./cs-flight-create play play`
+The blessing should almost always be "play".
 
-Which results in a $flight which can be used for the remainder of the
-configuration.
-
-Once you have an empty flights there are two main ways to populate it
-with jobs. Firstly you can create jobs from scratch using
-cs-job-create or secondly by copying one or more jobs from an existing
-template flight using "cs-adjust-flight copy-jobs". In either case the
-job can then be further customised using cs-adjust-flight to add and
-remove runvars etc.
-
-cs-job-create requires a flight ($flight from above), a job name (any
-string), a recipe (either custom, see below, or from any
-run-job/<recipe> in sg-run-job) and then the runvars in key=value
-form. Deciding on the runvars in particular can be tricky, it is
-usually easiest to copy an existing job.
-
-A job can be copied from a template flight using cs-adjust-flight
-copy-jobs e.g.:
-
-    $ ./cs-adjust-flight $flight copy-jobs $template <job-name>
+It is also possible to take full manual control and create an empty
+flight with cs-flight-create and then populate it with jobs using
+cs-job-create.  But, if you need jobs which are not copies or
+near-copies of existing jobs, it is normally easier to use
+`make-flight' (or one of its friends).
 
 Having created (or copied) a job then you may wish to customise, which
 can be done using cs-adjust-flight. In particular you can add or
@@ -720,11 +704,12 @@ remove runvars, see the doc comment at the top of the script. Most
 commonly you may which to preset the host ident to a specific if you
 are tracking down a host specific issue.
 
-You will also want to provide the necessary buildjobs for the job. You
-can do so by also copying the build jobs from your template job or by
+You will want to provide the necessary buildjobs for the job. You can
+do so by also copying the build jobs from your template job or by
 creating them by hand, or by setting the buildjob to reuse the builds
 done by the template, by setting the appropriate buildjob runvar to
-"$template.$job" . See "Common/Special Runvars" above for more.
+"$template.$job", as is done by the example above.
+See "Common/Special Runvars" above for more.
 
 Custom recipes can be placed in sg-run-job-adhoc and will be
 automatically included. At a minimum you will need to provide "proc