Improve trychange.py documentation. No logic change

trychange.py

 #!/usr/bin/env python
 # Copyright (c) 2012 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
 """Client-side script to send a try job to the try server. It communicates to
 the try server by either writting to a svn repository or by directly connecting
 to the server by HTTP.
 """
 
@@ skipping 517 matching lines @@
   group.add_option("--patchset", type='int',
                    help="Update rietveld issue try job status. This is "
                         "optional if --issue is used, In that case, the "
                         "latest patchset will be used.")
   group.add_option("--dry_run", action='store_true',
                    help="Don't send the try job. This implies --verbose, so "
                         "it will print the diff.")
   parser.add_option_group(group)
 
   group = optparse.OptionGroup(parser, "Try job options")
-  group.add_option("-b", "--bot", action="append",
-                    help="Only use specifics build slaves, ex: "
-                         "'--bot win,layout_mac'; see the try "
-                         "server waterfall for the slave's name")
+  group.add_option(
+      "-b", "--bot", action="append",
+      help=("IMPORTANT: specify ONE builder per --bot flag. Use it multiple "
+            "times to specify multiple builders. ex: "
+            "'-bwin_rel:ui_tests,webkit_unit_tests -bwin_layout'. See "
+            "the try server waterfall for the builders name and the tests "
+            "available. Can also be used to specify gtest_filter, e.g. "
+            "-bwin_rel:base_unittests:ValuesTest.*Value"))

[Nico, 2012/10/15 23:24:09]

Why this change? The lhs doc permitted "win,layout_mac", and that still seems to
work in practice. It's much more convenient to type too.

Can I revert this documentation change, and support ',' in `git cl try` too?

[Peter Mayo, 2012/10/15 23:41:41]

This leads to paths that are too hard to communicate unambiguously.

eg: 
win:ui_tests,layout_mac 
win,layout_mac:unit

in the end, picking one interpretation of these is going to end up with
situations that people aren't running the tests they think they are.

With one builder per bot: the interpretation & scope of test-limiting options is
 - clearer to people
 - easier to parse in python
 - more easily transformed by defaults
 - compared to requirements in the CQ

In other words, FWIW: -1.

   group.add_option("-B", "--print_bots", action="store_true",
                     help="Print bots we would use (e.g. from PRESUBMIT.py)"
                          " and exit.  Do not send patch.  Like --dry_run"
                          " but less verbose.")
   group.add_option("-r", "--revision",
                     help="Revision to use for the try job; default: the "
                          "revision will be determined by the try server; see "
                          "its waterfall for more info")
   group.add_option("-c", "--clobber", action="store_true",
                     help="Force a clobber before building; e.g. don't do an "
                          "incremental build")
   # TODO(maruel): help="Select a specific configuration, usually 'debug' or "
   #                    "'release'"
   group.add_option("--target", help=optparse.SUPPRESS_HELP)
 
   group.add_option("--project",
                    help="Override which project to use. Projects are defined "
                         "server-side to define what default bot set to use")
 
-  group.add_option("-t", "--testfilter", action="append", default=[],
-                   help="Add a gtest_filter to a test. Use multiple times to "
-                        "specify filters for different tests. (i.e. "
-                        "--testfilter base_unittests:ThreadTest.* "
-                        "--testfilter ui_tests) If you specify any testfilters "
-                        "the test results will not be reported in rietveld and "
-                        "only tests with filters will run.")
+  group.add_option(
+      "-t", "--testfilter", action="append", default=[],
+      help=("Apply a testfilter to all the selected builders. Unless the "
+            "builders configurations are similar, use multiple "
+            "--bot <builder>:<test> arguments."))
 
   parser.add_option_group(group)
 
   group = optparse.OptionGroup(parser, "Patch to run")
   group.add_option("-f", "--file", default=[], dest="files",
                    metavar="FILE", action="append",
                    help="Use many times to list the files to include in the "
                         "try, relative to the repository root")
   group.add_option("--diff",
                    help="File containing the diff to try")
@@ skipping 244 matching lines @@
     return 1
   except (gclient_utils.Error, subprocess2.CalledProcessError), e:
     print >> sys.stderr, e
     return 1
   return 0
 
 
 if __name__ == "__main__":
   fix_encoding.fix_encoding()
   sys.exit(TryChange(None, None, False))