From f6bbd2b5f4234327bdcad25038e0d2ff91e15094 Mon Sep 17 00:00:00 2001 From: Balazs Gibizer Date: Wed, 5 Apr 2017 16:17:42 +0200 Subject: [PATCH] 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 --- doc/source/reference/notifications.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/doc/source/reference/notifications.rst b/doc/source/reference/notifications.rst index 032fd9711fa6..0157ac2ff363 100644 --- a/doc/source/reference/notifications.rst +++ b/doc/source/reference/notifications.rst @@ -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/