openstack
/
nova
Code Issues Proposed changes

explain payload inheritance in notification devref 

During the implementation of I1c8c038078bbe1a5914a92d44b3e977287294a88
we realized that the inheritance used in the notification payload
classes has some drawbacks. When we need to introduce new leaf classes
the content of the nova.obj_name field will change in the emited
payload. This should be avoided if possible. If this cannot be avoided
and the only change is the renaming then the version of the new
payload shall be the same as the old payload was before the rename.
If the renaming involves any other changes on the payload (e.g. adding
new fields) then the version of the new payload shall be higher than
the old payload was.

Change-Id: Ie8c9317892f5593d473067d5dfc300a7e98795c5
This commit is contained in:
Balazs Gibizer 2017-04-05 16:17:42 +02:00
parent 5728a575c7
commit f6bbd2b5f4
1 changed files with 17 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
doc/source/reference/notifications.rst
View File

@ -96,6 +96,10 @@ notification payload:
consume the new payload without any change.
* a major version bump indicates a backward incompatible change of the payload
which can mean removed fields, type change, etc in the payload.
* there is an additional field 'nova_object.name' for every payload besides
'nova_object.data' and 'nova_object.version'. This field contains the name of
the nova internal representation of the payload type. Client code should not
depend on this name.
There is a Nova configuration parameter `notifications.notification_format`
that can be used to specify which notifications are emitted by Nova. The
@ -282,6 +286,17 @@ decorated with the `notification_sample` decorator. For example the
`doc/sample_notifications/service-update.json` and the
ServiceUpdateNotification class is decorated accordingly.
Notification payload classes can use inheritance to avoid duplicating common
payload fragments in nova code. However the leaf classes used directly in a
notification should be created with care to avoid future needs of adding extra
level of inheritance that changes the name of the leaf class as that name is
present in the payload class. If this cannot be avoided and the only change is
the renaming then the version of the new payload shall be the same as the old
payload was before the rename. See [3]_ as an example. If the renaming
involves any other changes on the payload (e.g. adding new fields) then the
version of the new payload shall be higher than the old payload was. See [4]_
as an example.
What should be in the notification payload
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is just a guideline. You should always consider the actual use case that
@ -317,3 +332,5 @@ Existing versioned notifications
.. [1] http://docs.openstack.org/developer/oslo.messaging/notifier.html
.. [2] http://docs.openstack.org/developer/oslo.versionedobjects
.. [3] https://review.openstack.org/#/c/463001/
.. [4] https://review.openstack.org/#/c/453077/