Update documentation according to suggestions

canonical · Jan 9, 2024 · 36772a1 · 36772a1
1 parent c4f131e
commit 36772a1
Show file tree

Hide file tree

Showing 11 changed files with 30 additions and 38 deletions.
diff --git a/docs/explanation/analysis.rst b/docs/explanation/analysis.rst
@@ -7,11 +7,3 @@ from Juju: the model status and the configuration for each application is obtain
 and stored in an Analysis object, divided into control and data plane. Each
 application is represented by a generic **OpenStackApplication** class or by a custom
 subclass, e.g. **Keystone(OpenStackApplication)**.
-
-Required Juju commands
-~~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: 
-
-    $ juju status
-    $ juju config <app-name>
diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst
@@ -11,4 +11,3 @@ and known issues.
    analysis
    planning
    upgrade
-   known-issues
diff --git a/docs/explanation/planning.rst b/docs/explanation/planning.rst
@@ -35,8 +35,3 @@ successfully.
 
 The plan can also be obtained without the need to perform cloud upgrade using
 the **plan** command. See :doc:`Plan an upgrade <../how-to/plan-upgrade>`.
-
-Required Juju commands
-~~~~~~~~~~~~~~~~~~~~~~
-
-No Juju commands are used.
diff --git a/docs/explanation/upgrade.rst b/docs/explanation/upgrade.rst
@@ -2,12 +2,7 @@
 Upgrade
 =======
 
-This phase is responsible for applying the upgrade plan step by step (See
-:doc:`Upgrade a cloud <../how-to/upgrade-cloud>`). By default steps are applied
-sequentially, but there are steps which can be run in parallel.
-
-Required Juju commands
-~~~~~~~~~~~~~~~~~~~~~~
-
-Any upgrade step may require different Juju commands, from changing configuration
-to running commands directly on a unit.
+This phase is responsible for applying the upgrade plan step by step (see
+:doc:`Upgrade a cloud <../how-to/upgrade-cloud>`). Most steps will be applied
+sequentially, but for some that are defined to be run in parallel, they will be
+executed in such a way.
diff --git a/docs/get-started/index.rst b/docs/get-started/index.rst
@@ -13,6 +13,9 @@ calling the juju status command.
     
     juju status --model <name-of-your-openstack-model>
 
+
+**COU** requires at minimum `write` permission to the target model.
+
 Installation
 ------------
 Install the **COU** snap from the `snap store`_:

diff --git a/docs/how-to/different-model.rst b/docs/how-to/different-model.rst
@@ -23,8 +23,7 @@ program. For example, `JUJU_DATA`_ can be used to specify a different path for J
 configuration files.
 
 .. code::
-    
-    $ JUJU_MODEL=openstack cou plan
+
     $ JUJU_DATA=./my-remote-cloud-juju-data cou plan
 
 .. LINKS

diff --git a/docs/how-to/no-backup.rst b/docs/how-to/no-backup.rst
@@ -1,6 +1,6 @@
-=====================================
-Upgrade without cloud database backup
-=====================================
+==========================================
+Plan/Upgrade without cloud database backup
+==========================================
 
 By default, **COU** plans for and runs a backup step of the cloud database before
 proceeding to actual upgrade steps. This can be turned off with `--no-backup`  flag.
@@ -23,13 +23,13 @@ Plan:
         Control Plane principal(s) upgrade plan
         Upgrade plan for 'rabbitmq-server' to victoria
             Upgrade software packages of 'rabbitmq-server' from the current APT repositories
-        …
+        ...
 
 Upgrade:
 
 .. code:: 
 
-    $ cou plan --no-backup --no-
+    $ cou upgrade --no-backup
     Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
     Connected to 'test-model' ✔
     Analyzing cloud... ✔
@@ -38,7 +38,16 @@ Upgrade:
     Running cloud upgrade...
     Verify that all OpenStack applications are in idle state ✔
     # note that there's no backup step being executed
-    Upgrade software packages of 'keystone' from the current APT repositories ✔
-    Upgrade 'keystone' to the new channel: 'victoria/stable' ✔
-    ...
+
+    Upgrade plan for 'rabbitmq-server' to victoria
+        Upgrade software packages of 'rabbitmq-server' from the current APT repositories
+        Upgrade 'rabbitmq-server' to the new channel: '3.9/stable'
+        Change charm config of 'rabbitmq-server' 'source' to 'cloud:focal-victoria'
+        Wait 1800s for model test-model to reach the idle state.
+        Check if the workload of 'rabbitmq-server' has been upgraded
+
+    Continue (y/n): y
+    Upgrade plan for 'rabbitmq-server' to victoria ✔
+    
+    ... # apply steps
     Upgrade completed.
diff --git a/docs/how-to/upgrade-cloud.rst b/docs/how-to/upgrade-cloud.rst
@@ -110,7 +110,7 @@ Usage example
     Continue (y/n): y
     Upgrade software packages of 'keystone' from the current APT repositories \
 
-    …  # apply each step
+    ...  # apply each step
     Upgrade completed.
 
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -33,11 +33,11 @@ In this documentation
 
    .. grid-item:: :doc:`Reference <reference/index>`
 
-      **Technical information** - available commands and environmental variables
+      **Technical information** - commands, environmental variables, and known issues
 
    .. grid-item:: :doc:`Explanation <explanation/index>`
 
-      **Additional information** - details of upgrade phases and known issues
+      **Additional information** - details of upgrade phases defined in **COU**
 
 
 .. toctree::

diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -9,3 +9,4 @@ This section explains the list of available commands and environmental variables
 
    commands
    environment-variables
+   known-issues
diff --git a/docs/explanation/known-issues.rst → docs/reference/known-issues.rst b/docs/explanation/known-issues.rst → docs/reference/known-issues.rst
@@ -2,8 +2,7 @@
 Known issues
 ============
 
-There are known upgrade bugs of the OpenStack that may help you troubleshoot an
-unsuccessful upgrade run: 
+Potential known upgrade bugs and non-standard procedures are listed in the OpenStack Charm Guide:
 
 - `Issues, charm procedures, and OpenStack upgrade notes`_