openstack
/
nova-specs
Code Issues Proposed changes

Usability improvements to the spec template 

Template should be easier to use with a little more structure
between the sections. Added a comment that people can add None instead
of deleting a section. This should help keep the use of the template
more consistent.

The sub-headings in implementation are renamed to match the existing
fields in launchpad. Should make parsing these easier at some point in
the future.

Tweaked the order so its closer to the current launchpad ordering.
Partly to ease the transition, party because I like the order they have
chosen.

Made a distinction between end-users, deployers and developers. This
has created much confusion in the past.

To reduce the text we force people to delete, trying out adding some
instructions as a comment block.

Change-Id: I28fae5c03da6939471109de7177ac7d2440e7680
This commit is contained in:
John Garbutt 2014-03-19 16:54:18 +00:00
parent b4253ee49c
commit 0df6270a95
1 changed files with 121 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
template.rst
View File

@ -1,109 +1,156 @@
::
#
# Copyright (C) 2014, <Copyright holder>
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
#
# Copyright 2014 <Copyright holder>
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
*Delete this paragraph when you write your blueprint.* Here are some
simple instructions. This template should be in ReSTructured text. The
filename in the git repository should match the launchpad URL, for example a
URL of https://blueprints.launchpad.net/nova/+spec/awesome-thing should be
named awesome-thing.rst .
..
This template should be in ReSTructured text. The filename in the git
repository should match the launchpad URL, for example a URL of
https://blueprints.launchpad.net/nova/+spec/awesome-thing should be named
awesome-thing.rst . Please do not delete any of the sections in this
template. If you have nothing to say for a whole section, just write: None
=============================
The title of your blueprint
=============================
Put the URL of your blueprint on launchpad here, as well as any other related
blueprints.
Include the URL of your launchpad blueprint:
https://blueprints.launchpad.net/nova/+spec/example
Introduction paragraph -- why are we doing anything? A single paragraph of
prose that operators can understand.
Detailed problem description
============================
A detailed description of the problem. For a new feature this might be use
cases. For a major reworking of something existing it would describe the
problems in that feature that are being addressed.
Problem description
===================
A detailed description of the problem:
- For a new feature this might be use cases.
- For a major reworking of something existing it would describe the
problems in that feature that are being addressed.
Proposed change
===============
Here is where you cover the change you propose to make. Some things to
consider:
Here is where you cover the change you propose to make in detail. How do you
propose to solve this problem?
- How will the feature be used? You could call this the user interface. It
might take various forms:
If this is one part of a larger effort make it clear where this piece ends. In
other words, what's the scope of this effort?
- For an API extension, API samples are required, *NOT* simply nova command
line examples.
Alternatives
------------
- Does this change have an impact on python-novaclient? What does the user
interface there look like?
What other ways could we do this thing? Why aren't we using those? This doesn't
have to be a full literature review, but it should demonstrate that thought has
been put into why the proposed solution is an appropriate one.
- If this change is a new binary, how would it be deployed?
End user impact
---------------
- Consistency of the user experience is also important. Some concrete examples:
How will the feature be used? You could call this the user interface. It
might take various forms:
- What config options are being added? Should they be more generic than
proposed (for example a flag that other hypervisor drivers might want to
implement as well)? Are the default values ones which will work well in
real deployments?
- For an API extension, API samples are required, *NOT* simply nova command
line examples.
- If the blueprint proposes a change to the driver API, discussion of how
other hypervisors would implement the feature is required.
- Does this change have an impact on python-novaclient? What does the user
interface there look like?
Deployer impact
---------------
Discuss things that will affect how you deploy and configure OpenStack,
such as:
- What config options are being added? Should they be more generic than
proposed (for example a flag that other hypervisor drivers might want to
implement as well)? Are the default values ones which will work well in
real deployments?
- If this change is a new binary, how would it be deployed?
- Please state anything that those doing continuous deployment, or those
upgrading from the previous release, need to be aware of. Also describe
any plans to deprecate configuration values or features. For example, if we
change the directory name that instances are stored in, how do we handle
instance directories created before the change landed? Do we move them? Do
we have a special case in the code? Do we assume that the operator will
recreate all the instances in their cloud?
Developer impact
----------------
Discuss things that will affect other developers working on OpenStack,
such as:
- If the blueprint proposes a change to the driver API, discussion of how
other hypervisors would implement the feature is required.
Implementation
==============
Assignee(s)
-----------
Who is leading the writing of the code? Or is this a blueprint where you're
throwing it out there to see who picks it up?
If more than one person is working on the implementation, please designate the
primary author and contact.
Primary assignee:
<launchpad-id or None>
Other contributors:
<launchpad-id or None>
Milestones
----------
Originally approved for:
Juno-1
Completed:
None
Work Items
----------
Work items or tasks -- break the feature up into the things that need to be
done to implement it. Those parts might end up being done by different people,
but we're mostly trying to understand the timeline for implementation.
- If this is one part of a larger effort make it clear where this piece ends.
In other words, what's the scope of this effort?
Dependencies
============
- Include specific references to specs in other projects that this one either
depends on or is related to.
- Include specific references to specs and/or blueprints in nova, or in other
projects, that this one either depends on or is related to.
- If this requires functionality of another project that is not currently used
by Nova (such as the glance v2 API when we previously only required v1),
document that fact.
- Does this feature require any new library dependencies or code otherwise not
included in OpenStack?
included in OpenStack? Or does it depend on a specific version of library?
Implementation
==============
Who is writing the code? Is anyone signed up to do the work? Or is this a
blueprint where you're throwing it out there to see who picks it up?
Work items or tasks -- break the feature up into the things that need to be
done to implement it. Those parts might end up being done by different people,
but we're mostly trying to understand the timeline for implementation.
Cover upgrade impact -- how will deploying this change affect existing users?
For example, if we change the directory name that instances are stored in,
how do we handle instance directories created before the change landed? Do we
move them? Do we have a special case in the code? Do we assume that the
operator will recreate all the instances in their cloud?
Alternative implementations
===========================
What other ways could we do this thing? Why aren't we using those? This doesn't
have to be a full literature review, but it should demonstrate that thought has
been put into why the proposed implementation is the appropriate one.
Testing
=======
@ -118,8 +165,10 @@ Is this untestable in gate given current limitations (specific hardware /
software configurations available)? If so, are there mitigation plans (3rd
party testing, gate enhancements, etc).
Documentation impact
Documentation Impact
====================
What is the impact on the docs team of this change? Some changes might require
donating resources to the docs team to have the documentation updated.
donating resources to the docs team to have the documentation updated. Don't
repeat details discussed above, but please reference them here.