04774d8f80
Add a section to our Coding Standards documentation that describes the use of reno for shade release notes. Change-Id: I87973c5b3f68727aa0cb1ccb9a82c90a8a32ebd1
3.8 KiB
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 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 Bunch objects, which help to maintain backward compatibility with a time when shade returned raw objects. Bunch allows the returned resource to act as both an object and a dict. Use of Bunch objects will eventually be deprecated in favor of just pure dicts, so do not depend on the Bunch object functionality. Expect a pure dict type.
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.