Fix doc comment on manager role change

Fixing the review comments from
- https://review.opendev.org/c/openstack/nova/+/953063

Implement blueprint policy-manager-role-default

Change-Id: Idf376d9bd2eea981206738d0217ddc578875b280
Signed-off-by: Ghanshyam Maan <gmaan@ghanshyammann.com>

doc/source/configuration/policy-concepts.rst

@@ -219,11 +219,11 @@ access within the requested project.
 
 ``project_manager`` is denoted by someone with the manager role on a project.
 It is intended to be used in project-level management APIs and perform more
-privileged operations than ``project_member`` on its project resources. It
+privileged operations on its project resources than ``project_member``. It
 inherits all the permissions of a ``project_member`` and ``project_reader``.
-For example, ``project_manager`` can migrate (cold or live) their server
+For example, a ``project_manager`` can migrate (cold or live) their servers
-without specifying the host. Further, the ``project_manager`` will be able
+without specifying the host. Further, a ``project_manager`` will be able
-to list their own project migrations.
+to list migrations related to their own project.
 
 ``project_manager`` persona in Nova policy rule (it is defined as
 ``project_manager_api`` in policy yaml) looks like:

releasenotes/notes/add-policy-manager-role-e245ba669eb88b26.yaml

@@ -1,35 +1,26 @@
 ---
 features:
   - |
-    The Nova policies introduce ``manager`` default roles provided by
+    Nova now supports a new default role ``manager``. This role is part of the
-    keystone. A ``project_manager`` denoted by someone with the ``manager``
+    standard role hierarchy supported by keystone. A new persona, the
-    role on a project. It is intended to perform more privileged operations
+    ``project_manager``, is denoted by someone with the ``manager`` role on a
-    than ``project_member`` on its project resources. To avoid any change in
+    specific project. The ``project_manager`` persona  is intended to perform
-    ``admin`` permissions, Nova use ``PROJECT_MANAGER_OR_ADMIN`` as default.
+    more privileged operations than a ``project_member`` while granting less
-
+    access than the global admin role. This brings the total set of personas
-    Currently, nova supports:
+    currently supported by Nova to:
 
     * ``admin``
     * ``project_manager``
     * ``project_member``
     * ``project_reader``
 
-    Currently, scope checks and new defaults are enabled by default. It is
+    To avoid any change in ``admin`` permissions, Nova uses
-    recommended to use new defaults but if your deployment need more time
+    ``PROJECT_MANAGER_OR_ADMIN`` as a default where manager access is granted.
-    then you can disable them by switching the below config option in
+    In this release, the below APIs policy are newly defaulted to
-    ``nova.conf`` file.:
-
-      [oslo_policy]
-      enforce_new_defaults=False
-      enforce_scope=False
-
-    Please refer `Policy New Defaults`_ for detail about policy new defaults.
-
-    In this release, the below APIs policy are default to
     ``PROJECT_MANAGER_OR_ADMIN``:
 
-    - ``os_compute_api:os-migrate-server:migrate`` ("Cold migrate a server
+    - ``os_compute_api:os-migrate-server:migrate`` (Cold migrate a server
-      without specifying a host")
+      without specifying a host)
     - ``os_compute_api:os-migrate-server:migrate_live`` (live migrate server
       without specifying host)
     - ``os_compute_api:os-migrations:index`` (List migrations without host
@@ -41,17 +32,18 @@ features:
     - ``os_compute_api:servers:migrations:delete`` (Delete(Abort) an
       in-progress live migration)
 
-    To introduced ``project_manager`` in migration APIs, we need to add a few
+    In addition, a number of new, more granular policies are introduced to
-    new policies.
+    allow us to use the ``project_manager`` persona in migration APIs:
 
-    * Live migrate:
+    * Live migration:
 
-      - Existing policy is used when live migrate server without specifying
+      - Existing policy is used when live migrating server without specifying
         host:
 
         - ``os_compute_api:os-migrate-server:migrate_live`` (live migrate
           server without specifying host)
         - Default: ``PROJECT_MANAGER_OR_ADMIN``
+
       - New policy is used when live migrate server to a specific host:
 
         - ``os_compute_api:os-migrate-server:migrate_live:host`` (live migrate
@@ -65,6 +57,7 @@ features:
         - ``os_compute_api:servers:migrations:index`` (Lists in-progress live
            migrations for a given server)
         - Default: ``PROJECT_MANAGER_OR_ADMIN``
+
       - New policy is used to host info in live migrations list:
 
         - ``os_compute_api:servers:migrations:index:host`` (Lists in-progress
@@ -78,6 +71,7 @@ features:
         - ``os_compute_api:os-migrations:index`` (List migrations without
           host info)
         - Default: ``PROJECT_MANAGER_OR_ADMIN``
+
       - New policy is used to host info in live migrations list:
 
         - ``os_compute_api:os-migrations:index:all_projects`` (List migrations
@@ -86,6 +80,18 @@ features:
         - ``os_compute_api:os-migrations:index:host`` (List migrations
           with host info)
         - Default: ``ADMIN``
+
+    Scope checks and new defaults are enabled by default and it is recommended
+    to use new defaults. However, if your deployment needs more time then you
+    can disable them by switching the below config option in ``nova.conf`` file.:
+
+      [oslo_policy]
+      enforce_new_defaults=False
+      enforce_scope=False
+
+    Please refer `Policy New Defaults`_ for detail about policy new defaults.
+
+    .. _Policy New Defaults: https://docs.openstack.org/nova/latest/configuration/policy-concepts.html
 upgrade:
   - |
     New policies are added to the live migration APIs with the same default.
@@ -98,11 +104,10 @@ upgrade:
       - ``os_compute_api:os-migrate-server:migrate_live``
       - ``os_compute_api:servers:migrations::index``
       - ``os_compute_api:os-migrations:index``
+
     - New policy:
 
       - ``os_compute_api:os-migrate-server:migrate_live:host``
       - ``os_compute_api:servers:migrations:index:host``
       - ``os_compute_api:os-migrations:index:all_projects``
       - ``os_compute_api:os-migrations:index:host``
-
-    .. _Policy New Defaults: https://docs.openstack.org/nova/latest/configuration/policy-concepts.html