Update the help text of bisect-builds.py tool.

tools/bisect-builds.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.
 
 """Snapshot Build Bisect Tool
 
 This script bisects a snapshot archive using binary search. It starts at
 a bad revision (it will try to guess HEAD) and asks for a last known-good
 revision. It will then binary search across this revision range by downloading,
@@ skipping 569 matching lines @@
   try:
     # Location of the latest build revision number
     return int(urllib.urlopen(url).read())
   except Exception, e:
     print('Could not determine latest revision. This could be bad...')
     return 999999999
 
 
 def main():
   usage = ('%prog [options] [-- chromium-options]\n'
-           'Perform binary search on the snapshot builds.\n'
+           'Perform binary search on the snapshot builds to find a minimal '
+           'range of revisions where a behavior change happened. The '
+           'behaviors are described as "good" and "bad". '
+           'It is NOT assumed that the behavior of the later revision is '
+           'the bad one.\n'
            '\n'
            'Tip: add "-- --no-first-run" to bypass the first run prompts.')
   parser = optparse.OptionParser(usage=usage)
   # Strangely, the default help output doesn't include the choice list.
   choices = ['mac', 'win', 'linux', 'linux64']
             # linux-chromiumos lacks a continuous archive http://crbug.com/78158
   parser.add_option('-a', '--archive',
                     choices = choices,
                     help = 'The buildbot archive to bisect [%s].' %
                            '|'.join(choices))
   parser.add_option('-o', action="store_true", dest='official_builds',
                     help = 'Bisect across official ' +
                     'Chrome builds (internal only) instead of ' +
                     'Chromium archives.')
   parser.add_option('-b', '--bad', type = 'str',
-                    help = 'The bad revision to bisect to. Default is HEAD.')
+                    help = 'A bad revision to start bisection. ' +
+                    'Default is HEAD.')

[scheib, 2013/01/04 22:41:09]

I think we should be explicit even here, which is where people will read for the
options. I suggest
"A bad revision to start bisection. May be earlier or later than the good
revision. Default ...". And similarly below.

[Bei Zhang, 2013/01/07 17:47:36]

Done.

   parser.add_option('-g', '--good', type = 'str',
-                    help = 'The last known good revision to bisect from. ' +
+                    help = 'A good revision to start bisection. ' +
                     'Default is 0.')
   parser.add_option('-p', '--profile', '--user-data-dir', type = 'str',
                     help = 'Profile to use; this will not reset every run. ' +
                     'Defaults to a clean profile.', default = 'profile')
   parser.add_option('-t', '--times', type = 'int',
                     help = 'Number of times to run each build before asking ' +
                     'if it\'s good or bad. Temporary profiles are reused.',
                     default = 1)
   (opts, args) = parser.parse_args()
 
@@ skipping 54 matching lines @@
     print 'WEBKIT CHANGELOG URL:'
     print '  ' + WEBKIT_CHANGELOG_URL % (max_webkit_rev, min_webkit_rev)
   print 'CHANGELOG URL:'
   if opts.official_builds:
     print OFFICIAL_CHANGELOG_URL % (min_chromium_rev, max_chromium_rev)
   else:
     print '  ' + CHANGELOG_URL % (min_chromium_rev, max_chromium_rev)
 
 if __name__ == '__main__':
   sys.exit(main())