This is a very terse set of points for reviewers to consider when looking at nova code. These are things that are important for the continued smooth operation of Nova, but that tend to be carried as “tribal knowledge” instead of being written down. It is an attempt to boil down some of those things into nearly checklist format. Further explanation about why some of these things are important belongs elsewhere and should be linked from here.
When making a change to the nova API, we should always follow the API WG guidelines rather than going for “local” consistency. Developers and reviewers should read all of the guidelines, but they are very long. So here are some key points:
- project should be used in the REST API instead of tenant.
- server should be used in the REST API instead of instance.
- compute should be used in the REST API instead of nova.
- URL should not include underscores; use hyphens (‘-‘) instead.
- The field names contained in a request/response body should use snake_case style, not CamelCase or Mixed_Case style.
- Synchronous resource creation: 201 Created
- Asynchronous resource creation: 202 Accepted
- Synchronous resource deletion: 204 No Content
- For all other successful operations: 200 OK
The central place where all config options should reside is the /nova/conf/ package. Options that are in named sections of nova.conf, such as [serial_console], should be in their own module. Options that are in the [DEFAULT] section should be placed in modules that represent a natural grouping. For example, all of the options that affect the scheduler would be in the scheduler.py file, and all the networking options would be moved to network.py.
A config option should be checked for:
A short description which explains what it does. If it is a unit (e.g. timeouts or so) describe the unit which is used (seconds, megabyte, mebibyte, ...).
A long description which shows the impact and scope. The operators should know the expected change in the behavior of Nova if they tweak this.
Hints which services will consume this config option. Operators/Deployers should not be forced to read the code to know which one of the services will change its behavior nor should they set this in every nova.conf file to be sure.
Descriptions/Validations for the possible values.
- If this is an option with numeric values (int, float), describe the edge cases (like the min value, max value, 0, -1).
- If this is a DictOpt, describe the allowed keys.
- If this is a StrOpt, list any possible regex validations, or provide a list of acceptable and/or prohibited values.
Interdependencies to other options. If other config options have to be considered when this config option gets changed, is this described?
Any change that is not tested well by the Jenkins check jobs must have a recent +1 vote from an appropriate third party test (or tests) on the latest patchset, before a core reviewer is allowed to make a +2 vote.
At a minimum, we must ensure that any technology specific code has a +1 from the relevant third party test, on the latest patchset, before a +2 vote can be applied. Specifically, changes to nova/virt/driver/<NNNN> need a +1 vote from the respective third party CI. For example, if you change something in the XenAPI virt driver, you must wait for a +1 from the XenServer CI on the latest patchset, before you can give that patch set a +2 vote.
This is important to ensure:
Please note:
- A new patch for the microversion API change in python-novaclient side should be submitted.
Nova uses reno for providing release notes in-tree. That means that a patch can include a reno file or a series can have a follow-on change containing that file explaining what the impact is.
A reno file is a YAML file written in the releasenotes/notes tree which is generated using the reno tool this way:
$ tox -e venv -- reno new <name-your-file>
where usually <name-your-file> can be bp-<blueprint_name> for a blueprint or bug-XXXXXX for a bugfix.
Refer to the reno documentation for the full list of sections.
A release note is required anytime a reno section is needed. Below are some examples for each section. Any sections that would be blank should be left out of the note file entirely. If no section is needed, then you know you don’t need to provide a release note :-)
Three sections are left intentionally unexplained (prelude, issues and other). Those are targeted to be filled in close to the release time for providing details about the soon-ish release. Don’t use them unless you know exactly what you are doing.