From 561ed634f47ffec30d3d9449087555a500f700c8 Mon Sep 17 00:00:00 2001
From: Matt Riedemann <mriedem.os@gmail.com>
Date: Wed, 21 Aug 2019 16:36:09 -0400
Subject: [PATCH] Document archive_deleted_rows return codes

The archive_deleted_rows command has a specific set of return
codes for both errors and flow control so we should document
those in the CLI guide.

A FIXME is left in the code because of the odd case of when
you could get 1 back meaning "we archived some stuff" or
"something really bad happened".

Change-Id: Id10bd286249ad68a841f2bfb3a3623b429b2b3cc
---
 doc/source/cli/nova-manage.rst | 23 +++++++++++++++++++++++
 nova/cmd/manage.py             |  5 +++++
 2 files changed, 28 insertions(+)

diff --git a/doc/source/cli/nova-manage.rst b/doc/source/cli/nova-manage.rst
index e826fca03687..f4ae60f81392 100644
--- a/doc/source/cli/nova-manage.rst
+++ b/doc/source/cli/nova-manage.rst
@@ -80,6 +80,29 @@ Nova Database
     for the purge, then run ``nova-manage db purge --before <date>`` manually
     after archiving is complete.
 
+    **Return Codes**
+
+    .. list-table::
+       :widths: 20 80
+       :header-rows: 1
+
+       * - Return code
+         - Description
+       * - 0
+         - Nothing was archived.
+       * - 1
+         - Some number of rows were archived.
+       * - 2
+         - Invalid value for ``--max_rows``.
+       * - 3
+         - No connection to the API database could be established using
+           :oslo.config:option:`api_database.connection`.
+       * - 4
+         - Invalid value for ``--before``.
+
+    If automating, this should be run continuously while the result is 1,
+    stopping at 0, or use the ``--until-complete`` option.
+
 ``nova-manage db purge [--all] [--before <date>] [--verbose] [--all-cells]``
     Delete rows from shadow tables. Specifying ``--all`` will delete all data from
     all shadow tables. Specifying ``--before`` will delete data from all shadow tables
diff --git a/nova/cmd/manage.py b/nova/cmd/manage.py
index e43eec1515ef..20056e0ff54d 100644
--- a/nova/cmd/manage.py
+++ b/nova/cmd/manage.py
@@ -2622,4 +2622,9 @@ def main():
             pdb.post_mortem()
         else:
             print(_("An error has occurred:\n%s") % traceback.format_exc())
+        # FIXME(mriedem): Some commands, like archive_deleted_rows, return 1
+        # for providing flow control to the caller, e.g. continue while rc=1
+        # until you get rc=0. If we fail in some unexpected way and return 1
+        # here, automation tools could continue indefinitely. This should
+        # probably be 255 instead.
         return 1