clarify operation of message.create when passed an exception and a detail

[Brian Rosmaita]

The create method in the message API takes various arguments, including an exception (can be None) and a message_field.Detail field (can also be None). The message_field.Detail class contains a mapping of exceptions to Detail fields for the convenience of being able to just pass an exception and have the message detail be created automatically. If you pass both an exception and a Detail, and the exception is mapped, the passed-in Detail is ignored. This seems counterintuitive, as it disallows providing a more fine-grained Detail when an exception is mapped. Unfortunately, I can't tell what the behavior is supposed to be from the message create docstring or from the current unit tests.

I propose changing the behavior so that the passed-in Detail is honored even in the case of a mapped exception and adding tests. If the team decides that the current behavior is correct, we'll still have tests to prevent regressions.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/648294

[Brian Rosmaita (brian-rosmaita)]

I did an analysis of the way messages are created in the current code, and have decided that the current behavior is correct [0].

This is because there are some situations where we just catch an Exception and pass it to message.create. Sometimes we have no idea what happened, so no detail is passed.
But there may be situations where we have a general idea of what the problem is, and can pass that as a detail.

But if we have a cinder.exception in such a case, we should prefer the mapped detail (not the passed-in one), because the mapped detail will be specific to that exception and will result in better info to the end user.

[0] https://etherpad.openstack.org/p/cinder-message-create

[Brian Rosmaita (brian-rosmaita)]

Will revise patch so the tests keep the current behavior and add some doc making it more clear how this is supposed to work.

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/648294
Committed: https://git.openstack.org/cgit/openstack/cinder/commit/?id=09c1111904410c22d16b850fa142e9e12f8c33c9
Submitter: Zuul
Branch: master

commit 09c1111904410c22d16b850fa142e9e12f8c33c9
Author: Brian Rosmaita <email address hidden>
Date: Wed Mar 27 18:46:10 2019 -0400

    Document behavior of message.create

    Add docstrings to clarify the behavior of message.create() when both
    an exception and detail are passed as arguments. Updates the
    user_messages section of the contributor docs to reflect the changes
    introduced in Pike by implementation of the "Explicit user messages"
    spec. Adds tests to prevent regressions.

    Closes-bug: #1822000
    Change-Id: Ia0425dc9c241d0c101057fbc534e68e7e5fdc317

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/cinder 15.0.0.0rc1 release candidate.