9cdd967550
There was a point in time in the past where we were gung ho on using Munch as a halfway house to get us to pure dicts. However, we released 1.0 before we could do that, so we're pretty stuck with them for the forseeable future. That's not terrible - they're pretty low overhead and work pretty well. Depends-On: Ie10099430481ffa76f5a19557e3693189544df6b Change-Id: I8b7dd2c4038db999280ec0c2c9c43fb9499e6d22
102 lines
3.7 KiB
ReStructuredText
102 lines
3.7 KiB
ReStructuredText
********************************
|
|
Shade Developer Coding Standards
|
|
********************************
|
|
|
|
In the beginning, there were no guidelines. And it was good. But that
|
|
didn't last long. As more and more people added more and more code,
|
|
we realized that we needed a set of coding standards to make sure that
|
|
the shade API at least *attempted* to display some form of consistency.
|
|
|
|
Thus, these coding standards/guidelines were developed. Note that not
|
|
all of shade adheres to these standards just yet. Some older code has
|
|
not been updated because we need to maintain backward compatibility.
|
|
Some of it just hasn't been changed yet. But be clear, all new code
|
|
*must* adhere to these guidelines.
|
|
|
|
Below are the patterns that we expect Shade developers to follow.
|
|
|
|
Release Notes
|
|
=============
|
|
|
|
Shade uses `reno <http://docs.openstack.org/developer/reno/>`_ for
|
|
managing its release notes. A new release note should be added to
|
|
your contribution anytime you add new API calls, fix significant bugs,
|
|
add new functionality or parameters to existing API calls, or make any
|
|
other significant changes to the code base that we should draw attention
|
|
to for the user base.
|
|
|
|
It is *not* necessary to add release notes for minor fixes, such as
|
|
correction of documentation typos, minor code cleanup or reorganization,
|
|
or any other change that a user would not notice through normal usage.
|
|
|
|
API Methods
|
|
===========
|
|
|
|
- When an API call acts on a resource that has both a unique ID and a
|
|
name, that API call should accept either identifier with a name_or_id
|
|
parameter.
|
|
|
|
- All resources should adhere to the get/list/search interface that
|
|
control retrieval of those resources. E.g., `get_image()`, `list_images()`,
|
|
`search_images()`.
|
|
|
|
- Resources should have `create_RESOURCE()`, `delete_RESOURCE()`,
|
|
`update_RESOURCE()` API methods (as it makes sense).
|
|
|
|
- For those methods that should behave differently for omitted or None-valued
|
|
parameters, use the `_utils.valid_kwargs` decorator. Notably: all Neutron
|
|
`update_*` functions.
|
|
|
|
- Deleting a resource should return True if the delete succeeded, or False
|
|
if the resource was not found.
|
|
|
|
Exceptions
|
|
==========
|
|
|
|
All underlying client exceptions must be captured and converted to an
|
|
`OpenStackCloudException` or one of its derivatives.
|
|
|
|
Client Calls
|
|
============
|
|
|
|
All underlying client calls (novaclient, swiftclient, etc.) must be
|
|
wrapped by a Task object.
|
|
|
|
Returned Resources
|
|
==================
|
|
|
|
Complex objects returned to the caller must be a dict type. The
|
|
methods `obj_to_dict()` or `obj_list_to_dict()` should be used for this.
|
|
|
|
As of this writing, those two methods are returning Munch objects, which help
|
|
to maintain backward compatibility with a time when shade returned raw
|
|
objects. Munch allows the returned resource to act as *both* an object
|
|
and a dict.
|
|
|
|
Nova vs. Neutron
|
|
================
|
|
|
|
- Recognize that not all cloud providers support Neutron, so never
|
|
assume it will be present. If a task can be handled by either
|
|
Neutron or Nova, code it to be handled by either.
|
|
|
|
- For methods that accept either a Nova pool or Neutron network, the
|
|
parameter should just refer to the network, but documentation of it
|
|
should explain about the pool. See: `create_floating_ip()` and
|
|
`available_floating_ip()` methods.
|
|
|
|
Tests
|
|
=====
|
|
|
|
- New API methods *must* have unit tests!
|
|
|
|
- Functional tests should be added, when possible.
|
|
|
|
- In functional tests, always use unique names (for resources that have this
|
|
attribute) and use it for clean up (see next point).
|
|
|
|
- In functional tests, always define cleanup functions to delete data added
|
|
by your test, should something go wrong. Data removal should be wrapped in
|
|
a try except block and try to delete as many entries added by the test as
|
|
possible.
|