Merge ~pelpsi/launchpad-buildd:qastaging-documentation-improvement into launchpad-buildd:master

[Simone Pelosi]

Improve documentation for qastaging deployment

[Jürgen Gmach (jugmac00)]

review: Approve

diff --git a/debian/changelog b/debian/changelog
index 8bddfae..f261f59 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,10 @@
+launchpad-buildd (237) UNRELEASED; urgency=medium
+
+  [ Simone Pelosi ]
+  * Improve documentation for qastaging deployment.
+
+ -- Simone Pelosi <[e-mail]>  Thu, 22 Feb 2024 17:16:55 +0100
+
 launchpad-buildd (236) focal; urgency=medium
 
   [ Colin Watson ]
diff --git a/docs/how-to/deployment.rst b/docs/how-to/deployment.rst
index 7365bee..aad49eb 100644
--- a/docs/how-to/deployment.rst
+++ b/docs/how-to/deployment.rst
@@ -42,11 +42,22 @@ Testing on qastaging
    <https://launchpad.net/~launchpad/+archive/ubuntu/buildd-staging/+packages>`__.
 
 #. Run ``mojo run -m manifest-rebuild-images`` in the management environment
-   (``stg-vbuilder@launchpad-bastion-ps5``) to start rebuilding images.
+   (``stg-vbuilder-qastaging@launchpad-bastion-ps5``) to start rebuilding images.
    After a minute or so, ``juju status glance-simplestreams-sync-\*`` will
    show "Synchronising images"; once this says "Sync completed", images have
    been rebuilt.
 
+   Note that if ``mojo run -m manifest-rebuild-images`` fails, run ``mojo run``
+   instead.
+
+   .. note::
+      Some glance-simplestreams-sync units may be in an unknown state:
+      as a consequence, the images that we have in OpenStack for the 
+      affected units are not updated. This will cause an `error
+      <https://pastebin.canonical.com/p/ChfGwsQNGJ/>`_ 
+      when you try to rebuild images blocking the execution of the script.
+      This doesn't happen using `mojo run`.
+
 #. Builders will get the new image after they finish their next build (or
    are disabled) and go through being reset.  Since qastaging's build farm
    is typically mostly idle, you can use ``manage-builders -l qastaging