Address nits from consumer generation

Address various minor issues from
https://review.openstack.org/#/c/565604/

Change-Id: I69df4c8d8c4b8813f78aeeb46f7b788d36238d35
Blueprint: add-consumer-generation

nova/api/openstack/placement/rest_api_version_history.rst

@@ -423,8 +423,11 @@ is not in the requested resources.
 
 A new generation field has been added to the consumer concept. Consumers are
 the actors that are allocated resources in the placement API. When an
-allocation is created, a consumer UUID is specified, along with a project and
-user ID (after microversion 1.8).
+allocation is created, a consumer UUID is specified. Starting with microversion
+1.8, a project and user ID are also required. If using microversions prior to
+1.8, these are populated from the ``incomplete_consumer_project_id`` and
+``incomplete_consumer_user_id`` config options from the ``[placement]``
+section.
 
 The consumer generation facilitates safe concurrent modification of an
 allocation.
@@ -445,22 +448,22 @@ itself is a dict, keyed by resource provider UUID, of allocations being
 consumed by the consumer with the ``{consumer_uuid}``. The top-level dict will
 also now contain a ``consumer_generation`` field.
 
-The value of the ``consumer_generation`` field will be an unsigned integer.
+The value of the ``consumer_generation`` field is opaque and should only be
+used to send back to subsequent operations on the consumer's allocations.
 
 The ``PUT /allocations/{consumer_uuid}`` URI has been modified to now require a
 ``consumer_generation`` field in the request payload. This field is required to
 be ``null`` if the caller expects that there are no allocations already
-existing for the consumer. Otherwise, it should contain the integer generation
-that the caller understands the consumer to be at the time of the call.
+existing for the consumer. Otherwise, it should contain the generation that the
+caller understands the consumer to be at the time of the call.
 
-A ``409 Conflict`` will be returned from the ``PUT
-/allocations/{consumer_uuid}`` if there was a mismatch between the supplied
-generation and the consumer's generation as known by the server. Similarly, a
-``409 Conflict`` will be returned if during the course of replacing the
-consumer's allocations another process concurrently changed the consumer's
-allocations. This allows the caller to react to the concurrent write by
-re-reading the consumer's allocations and re-issuing the call to replace
-allocations as needed.
+A ``409 Conflict`` will be returned from ``PUT /allocations/{consumer_uuid}``
+if there was a mismatch between the supplied generation and the consumer's
+generation as known by the server. Similarly, a ``409 Conflict`` will be
+returned if during the course of replacing the consumer's allocations another
+process concurrently changed the consumer's allocations. This allows the caller
+to react to the concurrent write by re-reading the consumer's allocations and
+re-issuing the call to replace allocations as needed.
 
 The ``PUT /allocations/{consumer_uuid}`` URI has also been modified to accept
 an empty allocations object, thereby bringing it to parity with the behaviour
@@ -479,14 +482,13 @@ involved in the request**. Similar responses to ``PUT
 generations conflict with the server's view of those consumers or if any of the
 consumers involved in the request are modified by another process.
 
-**WARNING**:
-
-In all cases, it is absolutely **NOT SAFE** to create and modify allocations
-for a consumer using different microversions where one of the microversions is
-prior to 1.28. The only way to safely modify allocations for a consumer and
-satisfy expectations you have regarding the prior existence (or lack of
-existence) of those allocations is to always use microversion 1.28+ when
-calling allocations API endpoints.
+.. warning:: In all cases, it is absolutely **NOT SAFE** to create and modify
+             allocations for a consumer using different microversions where one
+             of the microversions is prior to 1.28. The only way to safely
+             modify allocations for a consumer and satisfy expectations you
+             have regarding the prior existence (or lack of existence) of those
+             allocations is to always use microversion 1.28+ when calling
+             allocations API endpoints.
 
 1.29 Support allocation candidates with nested resource providers
 -----------------------------------------------------------------

placement-api-ref/source/parameters.yaml

@@ -320,8 +320,8 @@ consumer_generation:
   required: true
   min_version: 1.28
   description: >
-    The generation of the consumer. Should be set to ``None`` when indicating
-    the the caller expects the consumer does not yet exist.
+    The generation of the consumer. Should be set to ``null`` when indicating
+    that the caller expects the consumer does not yet exist.
 consumer_uuid_body:
   <<: *consumer_uuid
   in: body

releasenotes/notes/consumer_generation-f576ac2594b24e2e.yaml

@@ -3,15 +3,16 @@ features:
   - |
     Adds a new ``generation`` column to the consumers table. This value is
     incremented every time allocations are made for a consumer. The new
-    placement microversion 1.28 requires that all ``POST`` and ``PUT
-    /allocations`` requests now include the ``consumer_generation`` parameter
-    to ensure that if two processes are allocating resources for the same
-    consumer, the second one to post doesn't overwrite the first. If there is a
-    mismatch between the ``consumer_generation`` in the request and the current
-    value in the database, the allocation will fail, and a 409 Conflict
-    response will be returned. The calling process must then get the
-    allocations for that consumer by calling ``GET /allocations/{consumer}``.
-    That response will now contain, in addition to the allocations, the current
-    value of the generation value for that consumer. The calling process should
-    then combine the existing allocations with the ones it is trying to post,
-    and re-submit with the current consumer_generation.
+    placement microversion 1.28 requires that all ``POST /allocations`` and
+    ``PUT /allocations/{consumer_uuid}`` requests now include the
+    ``consumer_generation`` parameter to ensure that if two processes are
+    allocating resources for the same consumer, the second one to complete
+    doesn't overwrite the first. If there is a mismatch between the
+    ``consumer_generation`` in the request and the current value in the
+    database, the allocation will fail, and a 409 Conflict response will be
+    returned. The calling process must then get the allocations for that
+    consumer by calling ``GET /allocations/{consumer}``. That response will now
+    contain, in addition to the allocations, the current generation value for
+    that consumer. Depending on the use case, the calling process may error; or
+    it may wish to combine or replace the existing allocations with the ones it
+    is trying to post, and re-submit with the current consumer_generation.