Better help for build/latest-build

People can be confused by buildtag/desttag/target. Shed some light in
these commands' helps.

Fixes: https://pagure.io/koji/issue/1808

cli/koji_cli/commands.py

@@ -11,6 +11,7 @@ import random
 import re
 import stat
 import sys
+import textwrap
 import time
 import traceback
 from collections import OrderedDict, defaultdict
@@ -454,7 +455,20 @@ def handle_remove_pkg(goptions, session, args):
 
 def handle_build(options, session, args):
     "[build] Build a package from source"
-    usage = _("usage: %prog build [options] <target> <srpm path or scm url>")
+
+    usage = _("""\
+        usage: %prog build [options] <target> <srpm path or scm url>
+
+        First option is build target (don't confuse it with destination
+        tag (where build ends) or buildroot (from where dependencies
+        are installed).
+
+        List of all available targets can be acquired by "
+        'koji list-targets'. For further info about how tags, targets "
+        and buildroot interact, check the "
+        https://docs.pagure.org/koji/HOWTO/#package-organization""")
+
+    usage = textwrap.dedent(usage)
     parser = OptionParser(usage=get_usage_str(usage))
     parser.add_option("--skip-tag", action="store_true",
                       help=_("Do not attempt to tag package"))
@@ -2334,8 +2348,15 @@ def handle_revoke_cg_access(goptions, session, args):
 
 
 def anon_handle_latest_build(goptions, session, args):
-    "[info] Print the latest builds for a tag"
-    usage = _("usage: %prog latest-build [options] <tag> <package> [<package> ...]")
+    """[info] Print the latest builds for a tag"""
+    usage = _("""\
+        usage: %prog latest-build [options] <tag> <package> [<package> ...]
+
+        Note, that <tag> needn't be same as build target. If you've wanted to
+        see what was the latest build in given buildroot, check '%prog
+        list-targets --name=<target>' to find name of the buildroot's tag""")
+
+    usage = textwrap.dedent(usage)
     parser = OptionParser(usage=get_usage_str(usage))
     parser.add_option("--arch", help=_("List all of the latest packages for this arch"))
     parser.add_option("--all", action="store_true",

tests/test_cli/test_build.py

@@ -3,14 +3,11 @@ import mock
 import os
 import six
 import sys
-try:
-    import unittest2 as unittest
-except ImportError:
-    import unittest
 
 from koji_cli.commands import handle_build, _progress_callback
+from . import utils
 
-class TestBuild(unittest.TestCase):
+class TestBuild(utils.CliTestCase):
     # Show long diffs in error output...
     maxDiff = None
 
@@ -22,6 +19,20 @@ class TestBuild(unittest.TestCase):
         self.options.poll_interval = 0
         # Mock out the xmlrpc server
         self.session = mock.MagicMock()
+        self.error_format = """Usage: %s build [options] <target> <srpm path or scm url>
+
+First option is build target (don't confuse it with destination
+tag (where build ends) or buildroot (from where dependencies
+are installed).
+
+List of all available targets can be acquired by "
+'koji list-targets'. For further info about how tags, targets "
+and buildroot interact, check the "
+https://docs.pagure.org/koji/HOWTO/#package-organization
+(Specify the --help global option for a list of other help options)
+
+%s: error: {message}
+""" % (self.progname, self.progname)
 
     @mock.patch('sys.stdout', new_callable=six.StringIO)
     @mock.patch('koji_cli.commands.activate_session')
@@ -147,11 +158,7 @@ Task info: weburl/taskinfo?taskID=1
         actual_stdout = stdout.getvalue()
         actual_stderr = stderr.getvalue()
         expected_stdout = ''
-        expected_stderr = """Usage: %s build [options] <target> <srpm path or scm url>
-(Specify the --help global option for a list of other help options)
-
-%s: error: Exactly two arguments (a build target and a SCM URL or srpm file) are required
-""" % (progname, progname)
+        expected_stderr = self.format_error_message("Exactly two arguments (a build target and a SCM URL or srpm file) are required")
         self.assertMultiLineEqual(actual_stdout, expected_stdout)
         self.assertMultiLineEqual(actual_stderr, expected_stderr)
 
@@ -193,6 +200,15 @@ Task info: weburl/taskinfo?taskID=1
         actual_stdout = stdout.getvalue()
         actual_stderr = stderr.getvalue()
         expected_stdout = """Usage: %s build [options] <target> <srpm path or scm url>
+
+First option is build target (don't confuse it with destination
+tag (where build ends) or buildroot (from where dependencies
+are installed).
+
+List of all available targets can be acquired by "
+'koji list-targets'. For further info about how tags, targets "
+and buildroot interact, check the "
+https://docs.pagure.org/koji/HOWTO/#package-organization
 (Specify the --help global option for a list of other help options)
 
 Options:
@@ -259,11 +275,7 @@ Options:
         actual_stdout = stdout.getvalue()
         actual_stderr = stderr.getvalue()
         expected_stdout = ''
-        expected_stderr = """Usage: %s build [options] <target> <srpm path or scm url>
-(Specify the --help global option for a list of other help options)
-
-%s: error: --arch_override is only allowed for --scratch builds
-""" % (progname, progname)
+        expected_stderr = self.format_error_message("--arch_override is only allowed for --scratch builds")
         self.assertMultiLineEqual(actual_stdout, expected_stdout)
         self.assertMultiLineEqual(actual_stderr, expected_stderr)
 
@@ -354,11 +366,7 @@ Task info: weburl/taskinfo?taskID=1
         with self.assertRaises(SystemExit) as cm:
             handle_build(self.options, self.session, args)
         actual = stderr.getvalue()
-        expected = """Usage: %s build [options] <target> <srpm path or scm url>
-(Specify the --help global option for a list of other help options)
-
-%s: error: Unknown build target: target
-""" % (progname, progname)
+        expected = self.format_error_message( "Unknown build target: target")
         self.assertMultiLineEqual(actual, expected)
         # Finally, assert that things were called as we expected.
         activate_session_mock.assert_called_once_with(self.session, self.options)
@@ -405,11 +413,7 @@ Task info: weburl/taskinfo?taskID=1
         with self.assertRaises(SystemExit) as cm:
             handle_build(self.options, self.session, args)
         actual = stderr.getvalue()
-        expected = """Usage: %s build [options] <target> <srpm path or scm url>
-(Specify the --help global option for a list of other help options)
-
-%s: error: Unknown destination tag: dest_tag_name
-""" % (progname, progname)
+        expected = self.format_error_message("Unknown destination tag: dest_tag_name")
         self.assertMultiLineEqual(actual, expected)
         # Finally, assert that things were called as we expected.
         activate_session_mock.assert_called_once_with(self.session, self.options)
@@ -456,11 +460,7 @@ Task info: weburl/taskinfo?taskID=1
         with self.assertRaises(SystemExit) as cm:
             handle_build(self.options, self.session, args)
         actual = stderr.getvalue()
-        expected = """Usage: %s build [options] <target> <srpm path or scm url>
-(Specify the --help global option for a list of other help options)
-
-%s: error: Destination tag dest_tag_name is locked
-""" % (progname, progname)
+        expected = self.format_error_message("Destination tag dest_tag_name is locked")
         self.assertMultiLineEqual(actual, expected)
         # Finally, assert that things were called as we expected.
         activate_session_mock.assert_called_once_with(self.session, self.options)