ez: rename --dry-run-to to --preview-to

Based on some feedback and my own changing of mind, rename --dry-run-to
to --preview-to, in order to keep --dry-run unambiguous (nothing will be
changed or sent anywhere).

Suggested-by: Miquel Raynal <mraynal@kernel.org>
Link: 4e03211#r138312876
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

b4/command.py

@@ -341,8 +341,8 @@ def setup_parser() -> argparse.ArgumentParser:
                            help='Do not send, just dump out raw smtp messages to the stdout')
     sp_send_g.add_argument('-o', '--output-dir',
                            help='Do not send, write raw messages to this directory (forces --dry-run)')
-    sp_send_g.add_argument('--dry-run-to', nargs='+', metavar='ADDR',
-                           help='Like --dry-run, but sends out via email to specified recipients')
+    sp_send_g.add_argument('--preview-to', nargs='+', metavar='ADDR',
+                           help='Send everything for a pre-review to specified addresses instead of actual recipients')
     sp_send_g.add_argument('--reflect', action='store_true', default=False,
                            help='Send everything to yourself instead of the actual recipients')
 

b4/ez.py

@@ -1359,8 +1359,8 @@ def cmd_send(cmdargs: argparse.Namespace) -> None:
             logger.critical('          Stash or commit them first.')
             sys.exit(1)
 
-        if cmdargs.dry_run_to:
-            prefixes = ['DRYRUN']
+        if cmdargs.preview_to:
+            prefixes = ['PREVIEW']
         else:
             prefixes = None
 
@@ -1387,7 +1387,7 @@ def cmd_send(cmdargs: argparse.Namespace) -> None:
     excludes = set()
     pccs = dict()
 
-    if cmdargs.dry_run_to or cmdargs.no_trailer_to_cc:
+    if cmdargs.preview_to or cmdargs.no_trailer_to_cc:
         todests = list()
         ccdests = list()
     else:
@@ -1422,8 +1422,8 @@ def cmd_send(cmdargs: argparse.Namespace) -> None:
 
     tos = set()
     ccs = set()
-    if cmdargs.dry_run_to:
-        tos.update(cmdargs.dry_run_to)
+    if cmdargs.preview_to:
+        tos.update(cmdargs.preview_to)
     else:
         if cmdargs.to:
             tos.update(cmdargs.to)
@@ -1486,9 +1486,9 @@ def cmd_send(cmdargs: argparse.Namespace) -> None:
                 logger.debug('No sendemail configs found, will use the default web endpoint')
                 endpoint = DEFAULT_ENDPOINT
 
-    # Cannot currently use endpoint with --dry-run-to
-    if endpoint and cmdargs.dry_run_to:
-        logger.critical('CRITICAL: cannot use the web endpoint with --dry-run-to')
+    # Cannot currently use endpoint with --preview-to
+    if endpoint and cmdargs.preview_to:
+        logger.critical('CRITICAL: cannot use the web endpoint with --preview-to')
         sys.exit(1)
 
     # Give the user the last opportunity to bail out
@@ -1524,8 +1524,8 @@ def cmd_send(cmdargs: argparse.Namespace) -> None:
                 fromaddr = sconfig.get('from')
             if cmdargs.reflect:
                 logger.info('  - send the above messages to just %s (REFLECT MODE)', fromaddr)
-            elif cmdargs.dry_run_to:
-                logger.info('  - send the above messages to the DRY-RUN recipients listed')
+            elif cmdargs.preview_to:
+                logger.info('  - send the above messages to the recipients listed (PREVIEW MODE)')
             else:
                 logger.info('  - send the above messages to actual listed recipients')
             logger.info('  - with envelope-from: %s', fromaddr)
@@ -1547,7 +1547,7 @@ def cmd_send(cmdargs: argparse.Namespace) -> None:
             else:
                 logger.info('  - via SMTP server %s', smtpserver)
 
-        if not (cmdargs.reflect or cmdargs.resend or cmdargs.dry_run_to):
+        if not (cmdargs.reflect or cmdargs.resend or cmdargs.preview_to):
             logger.info('  - tag and reroll the series to the next revision')
         logger.info('')
         if cmdargs.reflect:
@@ -1664,8 +1664,8 @@ def cmd_send(cmdargs: argparse.Namespace) -> None:
     if cmdargs.resend:
         logger.debug('Not updating cover/tracking on resend')
         return
-    if cmdargs.dry_run_to:
-        logger.debug('Not updating cover/tracking on --dry-run-to')
+    if cmdargs.preview_to:
+        logger.debug('Not updating cover/tracking on --preview-to')
         return
 
     reroll(mybranch, tag_msg, cl_msgid)

docs/contributor/send.rst

@@ -178,6 +178,22 @@ When ``--reflect`` is on:
 * your branch will **not** be automatically rerolled to the next
   revision
 
+Checking things over with ``--preview-to`` **(v0.13+)**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sometimes you want to ask your friend, colleague, boss, or mentor to
+give your submission a quick review. You can send them your series using
+``--preview-to boss@example.com`` before you send things out to the
+actual maintainers.
+
+When ``--preview-to`` is on:
+
+* b4 will **only send to the addresses you specify on the command line**
+* your branch will **not** be automatically rerolled to the next
+  revision
+
+(NB: the web submission endpoint cannot currently be used for this
+feature.)
+
 What happens after you send
 ---------------------------
 The following happens after you send your patches:
@@ -211,6 +227,13 @@ Command line flags
   actually sending things out and lets you verify that all patches are
   looking good and all recipients are correctly set.
 
+``--preview-to`` **(v0.13+)**
+  Sometimes it is useful to send your series for a pre-review to a
+  colleague, mentor, boss, etc. Using this option will send out the
+  series to the addresses specified on the command line, but will not
+  reroll your series, allowing you to send the actual submission at some
+  later point.
+
 ``--reflect`` **(v0.11+)**
   Prepares everything for sending, but only emails yourself (the address
   in the ``From:`` header). Useful as a last check to make sure that

man/b4.5

@@ -620,7 +620,7 @@ Enroll current branch, using the passed tag, branch, or commit as fork base
 .INDENT 0.0
 .TP
 .B usage:
-b4 send [\-h] [\-d | \-o OUTPUT_DIR | \-\-dry\-run\-to ADDR [ADDR ...] | \-\-reflect] [\-\-no\-trailer\-to\-cc] [\-\-to ADDR [ADDR ...]] [\-\-cc ADDR [ADDR ...]] [\-\-not\-me\-too] [\-\-resend [vN]] [\-\-no\-sign] [\-\-web\-auth\-new] [\-\-web\-auth\-verify VERIFY_TOKEN]
+b4 send [\-h] [\-d | \-o OUTPUT_DIR | \-\-preview\-to ADDR [ADDR ...] | \-\-reflect] [\-\-no\-trailer\-to\-cc] [\-\-to ADDR [ADDR ...]] [\-\-cc ADDR [ADDR ...]] [\-\-not\-me\-too] [\-\-resend [vN]] [\-\-no\-sign] [\-\-web\-auth\-new] [\-\-web\-auth\-verify VERIFY_TOKEN]
 .TP
 .B options:
 .INDENT 7.0
@@ -633,8 +633,8 @@ Do not send, just dump out raw smtp messages to the stdout
 .UNINDENT
 .INDENT 7.0
 .TP
-.B \-\-dry\-run\-to ADDR [ADDR ...]
-Like \-\-dry\-run, but sends out via email to specified recipients
+.B \-\-preview\-to ADDR [ADDR ...]
+Send everything for a pre\-review to specified addresses instead of actual recipients
 .UNINDENT
 .INDENT 7.0
 .TP

man/b4.5.rst

@@ -401,14 +401,14 @@ Enroll existing branch:
 b4 send
 ~~~~~~~
 usage:
-  b4 send [-h] [-d | -o OUTPUT_DIR | --dry-run-to ADDR [ADDR ...] | --reflect] [--no-trailer-to-cc] [--to ADDR [ADDR ...]] [--cc ADDR [ADDR ...]] [--not-me-too] [--resend [vN]] [--no-sign] [--web-auth-new] [--web-auth-verify VERIFY_TOKEN]
+  b4 send [-h] [-d | -o OUTPUT_DIR | --preview-to ADDR [ADDR ...] | --reflect] [--no-trailer-to-cc] [--to ADDR [ADDR ...]] [--cc ADDR [ADDR ...]] [--not-me-too] [--resend [vN]] [--no-sign] [--web-auth-new] [--web-auth-verify VERIFY_TOKEN]
 
 options:
   -h, --help            show this help message and exit
   -d, --dry-run         Do not send, just dump out raw smtp messages to the stdout
 
-  --dry-run-to ADDR [ADDR ...]
-                        Like --dry-run, but sends out via email to specified recipients
+  --preview-to ADDR [ADDR ...]
+                        Send everything for a pre-review to specified addresses instead of actual recipients
 
   -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                         Do not send, write raw messages to this directory (forces --dry-run)