Update template
Add a few sections from the nova template, and some details that are only useful to oslo projects. Change-Id: I7ba6bd47321dc0ba3a2806881eb0f0a886dcd65d
This commit is contained in:
Doug Hellmann
parent
2bfba07d2e
commit
09d3a39cf6
|
|
@ -1,14 +1,26 @@
|
|||
..
|
||||
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/oslo/+spec/awesome-thing should be named
|
||||
awesome-thing.rst.
|
||||
This template should be in ReSTructured text. For help with syntax,
|
||||
see http://sphinx-doc.org/rest.html
|
||||
|
||||
To test out your formatting, build the docs using tox, or see:
|
||||
http://rst.ninjs.org
|
||||
|
||||
The filename in the git repository should match the launchpad URL,
|
||||
for example a URL of
|
||||
https://blueprints.launchpad.net/oslo/+spec/awesome-thing should be
|
||||
named awesome-thing.rst.
|
||||
|
||||
Please wrap text at 79 columns.
|
||||
|
||||
Please do not delete any of the sections in this
|
||||
template. If you have nothing to say for a whole section, just write: None
|
||||
|
||||
For help with syntax, see http://sphinx-doc.org/rest.html
|
||||
To test out your formatting, see http://www.tele3.cz/jbar/rest/rest.html
|
||||
If you would like to provide a diagram with your spec, ascii diagrams are
|
||||
required. http://asciiflow.com/ is a very nice tool to assist with making
|
||||
ascii diagrams. The reason for this is that the tool used to review specs is
|
||||
based purely on plain text. Plain text will allow review to proceed without
|
||||
having to look at additional files which can not be viewed in gerrit. It
|
||||
will also allow inline feedback on the diagram itself.
|
||||
|
||||
=============================
|
||||
The title of your blueprint
|
||||
|
|
@ -16,7 +28,7 @@
|
|||
|
||||
Include the URL of your launchpad blueprint:
|
||||
|
||||
https://blueprints.launchpad.net//+spec/example
|
||||
https://blueprints.launchpad.net/oslo/+spec/example
|
||||
|
||||
Introduction paragraph -- why are we doing anything?
|
||||
|
||||
|
|
@ -25,6 +37,12 @@ Problem description
|
|||
|
||||
A detailed description of the problem.
|
||||
|
||||
* For a new feature this might be use cases. Ensure you are clear about the
|
||||
actors in each use case: End User vs Deployer
|
||||
|
||||
* For a major reworking of something existing it would describe the
|
||||
problems in that feature that are being addressed.
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
|
|
@ -34,13 +52,119 @@ propose to solve this problem?
|
|||
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?
|
||||
|
||||
Include where in the oslo tree hierarchy this will reside.
|
||||
Include information about which oslo repository will receive the
|
||||
change, including creating new repositories for libraries being
|
||||
graduated and backports to the incubator if necessary. List the files
|
||||
to be updated or added.
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
This is an optional section, where it does apply we'd just like a demonstration
|
||||
that some thought has been put into why the proposed approach is the best one.
|
||||
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.
|
||||
|
||||
Impact on Existing APIs
|
||||
-----------------------
|
||||
|
||||
If the change requires modifying the API of an existing oslo module or
|
||||
library, summarize those changes ("add foo argument to Blah
|
||||
constructor"). Describe how the changes can be made in a
|
||||
backwards-compatible way (required for libraries) or why that is not
|
||||
needed (desired but not required for incubated code).
|
||||
|
||||
Security impact
|
||||
---------------
|
||||
|
||||
Describe any potential security impact on the system. Some of the items to
|
||||
consider include:
|
||||
|
||||
* Does this change touch sensitive data such as tokens, keys, or user data?
|
||||
|
||||
* Does this change alter the API in a way that may impact security, such as
|
||||
a new way to access sensitive information or a new way to login?
|
||||
|
||||
* Does this change involve cryptography or hashing?
|
||||
|
||||
* Does this change require the use of sudo or any elevated privileges?
|
||||
|
||||
* Does this change involve using or parsing user-provided data? This could
|
||||
be directly at the API level or indirectly such as changes to a cache layer.
|
||||
|
||||
* Can this change enable a resource exhaustion attack, such as allowing a
|
||||
single API interaction to consume significant server resources? Some examples
|
||||
of this include launching subprocesses for each connection, or entity
|
||||
expansion attacks in XML.
|
||||
|
||||
For more detailed guidance, please see the OpenStack Security Guidelines as
|
||||
a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These
|
||||
guidelines are a work in progress and are designed to help you identify
|
||||
security best practices. For further information, feel free to reach out
|
||||
to the OpenStack Security Group at openstack-security@lists.openstack.org.
|
||||
|
||||
Performance Impact
|
||||
------------------
|
||||
|
||||
Describe any potential performance impact on the system, for example
|
||||
how often will new code be called, and is there a major change to the calling
|
||||
pattern of existing code.
|
||||
|
||||
Examples of things to consider here include:
|
||||
|
||||
* A periodic task might look like a small addition but if it calls conductor or
|
||||
another service the load is multiplied by the number of nodes in the system.
|
||||
|
||||
* Scheduler filters get called once per host for every instance being created,
|
||||
so any latency they introduce is linear with the size of the system.
|
||||
|
||||
* A small change in a utility function or a commonly used decorator can have a
|
||||
large impacts on performance.
|
||||
|
||||
* Calls which result in database queries (whether direct or via conductor)
|
||||
can have a profound impact on performance when called in critical sections of
|
||||
the code.
|
||||
|
||||
* Will the change include any locking, and if so what considerations are there
|
||||
on holding the lock?
|
||||
|
||||
Configuration Impact
|
||||
--------------------
|
||||
|
||||
Does this change introduce any new configuration options? Describe the
|
||||
possible valid settings.
|
||||
|
||||
Will the default values work well in real deployments?
|
||||
|
||||
Should the new options be more generic than proposed (for example a
|
||||
flag that other drivers might want to implement as well)?
|
||||
|
||||
Why is a new configuration option needed, instead of choosing a single
|
||||
behavior?
|
||||
|
||||
If a configuration option is being renamed, or moved into an option
|
||||
group, describe those changes.
|
||||
|
||||
Describe plans to deprecate configuration options, including the
|
||||
upgrade/migration path for anyone doing continuous deployment.
|
||||
|
||||
Developer Impact
|
||||
----------------
|
||||
|
||||
Discuss things that will affect other developers working on OpenStack,
|
||||
such as:
|
||||
|
||||
* If the blueprint proposes a change to a driver API within a library
|
||||
like oslo.messaging, discuss how other drivers would implement the
|
||||
feature.
|
||||
|
||||
* If the blueprint proposes modifying an existing module being used by
|
||||
one or more apps, what will need to change in those apps to
|
||||
accommodate the change here? For example, when graduating a module
|
||||
from the incubator, does the app need a new "interface module" to
|
||||
hold global values previously held in the incubated module? Have the
|
||||
semantics of the module changed enough to require significant
|
||||
modifications to the consuming applications? API changes described
|
||||
above can be referenced here without repeating the details.
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
|
@ -57,8 +181,8 @@ primary author and contact.
|
|||
Primary assignee:
|
||||
<launchpad-id or None>
|
||||
|
||||
Can optionally can list additional ids if they intend on doing
|
||||
substantial implementation work on this blueprint.
|
||||
Other contributors:
|
||||
<launchpad-id or None>
|
||||
|
||||
Milestones
|
||||
----------
|
||||
|
|
@ -73,6 +197,51 @@ 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.
|
||||
|
||||
For graduation blueprints, start with
|
||||
https://wiki.openstack.org/wiki/Oslo/CreatingANewLibrary#Checklist and
|
||||
add any additional steps necessary at the appropriate place in the
|
||||
sequence. If no extra work is needed, referencing the checklist
|
||||
without reproducing it is sufficient.
|
||||
|
||||
Incubation
|
||||
==========
|
||||
|
||||
If this work reflects the addition of a new module through the
|
||||
incubator process, we want to ensure that the full life-cycle for the
|
||||
module has been thought out.
|
||||
|
||||
Adoption
|
||||
--------
|
||||
|
||||
Which applications would like to share the modules? We usually prefer
|
||||
at least 2 applications, but if too many applications share the
|
||||
incubated version graduation becomes more difficult.
|
||||
|
||||
Library
|
||||
-------
|
||||
|
||||
Which library will the new module eventually graduate into? If this is
|
||||
a new library, explain why no existing library is suitable (circular
|
||||
dependencies, no existing related library, etc.) and give a brief
|
||||
description of the new library.
|
||||
|
||||
Remember to consider the dependencies of the library. Will it depend
|
||||
on other oslo libraries that it does not already use? Will those
|
||||
dependencies introduce a cycle?
|
||||
|
||||
Anticipated API Stabilization
|
||||
-----------------------------
|
||||
|
||||
What API changes are anticipated before the code will be stable enough
|
||||
to graduate? How many release cycles are needed for that API to prove
|
||||
itself?
|
||||
|
||||
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. Don't
|
||||
repeat details discussed above, but please reference them here.
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
|
@ -83,6 +252,26 @@ Dependencies
|
|||
- Does this feature require any new library dependencies or code otherwise not
|
||||
included in OpenStack? Or does it depend on a specific version of library?
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
Please add any useful references here. You are not required to have any
|
||||
reference. Moreover, this specification should still make sense when your
|
||||
references are unavailable. Examples of what you could include are:
|
||||
|
||||
* Links to mailing list or IRC discussions
|
||||
|
||||
* Links to notes from a summit session
|
||||
|
||||
* Links to relevant research, if appropriate
|
||||
|
||||
* Related specifications as appropriate (e.g. if it's an EC2 thing, link the
|
||||
EC2 docs)
|
||||
|
||||
* Anything else you feel it is worthwhile to refer to
|
||||
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
This work is licensed under a Creative Commons Attribution 3.0
|
||||
|
|
|
|||
Loading…
Reference in New Issue