This change provides a small number of updates to the placement user and
contributor documentation to reflect some of the things that have
changed recently. This is by no means complete, but is an improvement
over what was there.
Partial-Bug: #1778227
Change-Id: Ia348cd3c99b1a5104e15595fdebc83e1ca582a98
This ensures we have version-specific references to other projects [1].
Note that this doesn't mean the URLs are actually valid - we need to do
more work (linkcheck?) here, but it's an improvement nonetheless.
[1] https://docs.openstack.org/openstackdocstheme/latest/#external-link-helper
Change-Id: Ifb99e727110c4904a85bc4a13366c2cae300b8df
A todo in the contributor/placement.rst slipped through the review
cracks and meant a bad link to 'link to spec once it merges' is in the
docs. This fixes it with the correct link to the spec.
Change-Id: I13daf9576dcb1229409826b4c4eac28c8bb1e23f
The API-sig has a guideline[1] for including error codes in error
responses to help distinguish errors with the same status code
from one another. This change provides a simplest-thing-that-could-
possibly-work solution to make that go.
This solution comes about after a few different constraints and attempts:
* We would prefer to go on using the existing webob.exc exceptions, not
make subclasses.
* We already have a special wrapper around our wsgi apps to deal with
setting the json_error_formatter.
* Though webob allows custom Request and Response objects, it uses the
default Response object as the parent of the HTTP exceptions.
* The Response object accepts kwargs, but only if they can be associated
with known attributes on the class. Since we can't subclass...
* The json_error_formatter method is not passed the raw exception, but
it does get the current WSGI environ
* The webob.exc classes take a 'comment' kwarg that is not used, but
is also not passed to the json_error_formatter.
Therefore, when we raise an exception, we can set 'comment' to a code
and then assign that comment to a well known field in the environ and if
that environ is set in json_error_formatter, we can set 'code' in the
output.
This is done in a new microversion, 1.23. Every response gets a default
code 'placement.undefined_code' from 1.23 on. Future development will
add specific codes where required. This change adds a stub code for
inventory in use when doing a PUT to .../inventories but the name
may need improvement.
[1] http://specs.openstack.org/openstack/api-wg/guidelines/errors.html
Implements blueprint placement-api-error-handling
Change-Id: I9a833aa35d474caa35e640bbad6c436a3b16ac5e
A recent IRC conversation [1] discussed that there are generally no tests
for the placement handler code (the wsgi methods that respond to each
URI and HTTP method). This change adds a paragraph to point out that
this is mostly intentional and that when they get complex it would
be a good idea to extract a method.
[1] http://eavesdrop.openstack.org/irclogs/%23openstack-nova/%23openstack-nova.2018-03-28.log.html#t2018-03-28T13:00:40
Change-Id: I09774c123068e42e6a828fc37455dc5d374486b9
This udpates the placement contributor documentation to reflect the
current state of affairs. Ininitially this was just going to be an
update to reflect that the oslo versioned objects had moved. However,
while reviewing the rest of the doc it became clear there were other
issues that should be resolved. Doing so in one shot helps to maintain
the continuity of the document and doing it piecemeal means it is less
likely to happen.
Change-Id: Ia8d4861799e27a30108dd465d15828c5a1943819
In the comments to I8f0c3006d1bb97d228f73256c58a79235cd12670, a request
for clarification was made on when the last-modified header should
be "now". This adds an example to help things a bit more clear.
Change-Id: I301f17bc7aad9f0037d2b13aa6e493ac9a6abb80
Add some instructions on how and when to add last-modified headers
when creating a new handler in the placement API.
Change-Id: I8f0c3006d1bb97d228f73256c58a79235cd12670
I put out a new placement microversion [1] and initially missed updating
the API reference documentation [2]. I'd like to say it would have
helped if the checklist in the Microversion section of the contributor
doc had been up to date, except I didn't even know about that document
at the time. Anyway, this change set adds that bullet - and I'll know
to refer to it next time.
[1] https://review.openstack.org/499826
[2] https://review.openstack.org/515748
Change-Id: Id0329d9824eeb1d210defe0567286372b72cb1cf
Per the spec [1]:
user/ – end-user content such as concept guides, advice, tutorials,
step-by-step instructions for using the CLI to perform specific tasks,
etc.
The remaining content all ends up in here.
[1] specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration
Change-Id: I480eee9cd7568efe2f76dd185004774588eb4a99
Per the spec [1]:
contributor/ – anything related to contributing to the project or how
the team is managed. Applies to some of the current content under
/developer, we are changing the name to emphasize that not all
contributors are developers and sometimes developers are users but not
contributors.
We currently have a handful of docs that focus on the "how to develop or
contribute" aspects of nova, and these are moved. Docs that focus on
architecture or design decisions for nova are not moved, as these will
go into 'reference'.
A TODO is added to the former 'api_plugins' document as it's mega
out-of-date and needs some serious work.
[1] specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration
Change-Id: Iad770688b4eafeb9caa710b4398b02d80a017a70
Chris Dent