openstack/nova
Code Issues Proposed changes

Merge "explain payload inheritance in notification devref"

Browse Source
This commit is contained in:
Jenkins
2017-09-06 13:29:59 +00:00
committed by Gerrit Code Review
parent ffa86cf200 f6bbd2b5f4
commit fa1ac7d965
1 changed files with 17 additions and 0 deletions
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. consume the new payload without any change.
* a major version bump indicates a backward incompatible change of the payload * a major version bump indicates a backward incompatible change of the payload
which can mean removed fields, type change, etc in 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` There is a Nova configuration parameter `notifications.notification_format`
that can be used to specify which notifications are emitted by Nova. The 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 `doc/sample_notifications/service-update.json` and the
ServiceUpdateNotification class is decorated accordingly. 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 What should be in the notification payload
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is just a guideline. You should always consider the actual use case that This is just a guideline. You should always consider the actual use case that
@@ -320,3 +335,5 @@ Existing versioned notifications
.. [1] http://docs.openstack.org/developer/oslo.messaging/notifier.html .. [1] http://docs.openstack.org/developer/oslo.messaging/notifier.html
.. [2] http://docs.openstack.org/developer/oslo.versionedobjects .. [2] http://docs.openstack.org/developer/oslo.versionedobjects
.. [3] https://review.openstack.org/#/c/463001/
.. [4] https://review.openstack.org/#/c/453077/