openstack/barbican-specs
Code Issues Proposed changes

Update README and specs/template.rst

Browse Source 
Updated to remove leftover copy/paste references to Nova, as well
as our use of Storyboard instead of Launchpad.

Change-Id: Ie4c3d86eb4751151409006c817e4da7524d7e39a
This commit is contained in:
Douglas Mendizábal
2019-05-23 16:44:58 -05:00
parent a978514892
commit cb26767dd4
2 changed files with 26 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
README.rst
View File

@@ -1,17 +1,11 @@
========================
Team and repository tags
========================
.. image:: https://governance.openstack.org/badges/barbican-specs.svg
:target: https://governance.openstack.org/tc/reference/tags/index.html
.. Change things from this point on
================================== ==================================
OpenStack Barbican Specifications OpenStack Barbican Specifications
================================== ==================================
This git repository is used to hold approved design specifications for additions .. image:: https://governance.openstack.org/badges/barbican-specs.svg
:target: https://governance.openstack.org/tc/reference/tags/index.html
This git repository is used to hold approved design specifications for changes
to the Barbican project. Reviews of the specs are done in gerrit, using a similar to the Barbican project. Reviews of the specs are done in gerrit, using a similar
workflow to how we review and merge changes to the code itself. workflow to how we review and merge changes to the code itself.
@@ -24,9 +18,13 @@ You can find an example spec in `specs/template.rst`.
Specifications are proposed for a given release by adding them to the Specifications are proposed for a given release by adding them to the
`specs/<release>` directory and posting it for review. The implementation `specs/<release>` directory and posting it for review. The implementation
status of a blueprint for a given release can be found by looking at the status of a blueprint for a given release can be found by looking at the
blueprint in launchpad. Not all approved blueprints will get fully implemented. `story in storyboard`__. Not all approved blueprints will get fully implemented.
Specifications have to be re-proposed for every release. The review may be .. _Storyboard: https://storyboard.openstack.org/#!/project/openstack/barbican-specs
__ Storyboard_
Specifications have to be re-submitted for every release. The review may be
quick, but even if something was previously approved, it should be re-reviewed quick, but even if something was previously approved, it should be re-reviewed
to make sure it still makes sense as written. to make sure it still makes sense as written.
@@ -36,11 +34,6 @@ blueprints::
http://blueprints.launchpad.net/barbican http://blueprints.launchpad.net/barbican
Please note, Launchpad blueprints are still used for tracking the
current status of blueprints. For more information, see::
https://wiki.openstack.org/wiki/Blueprints
For more information about working with gerrit, see:: For more information about working with gerrit, see::
https://docs.openstack.org/infra/manual/developers.html#development-workflow https://docs.openstack.org/infra/manual/developers.html#development-workflow
@@ -51,4 +44,4 @@ confidence in the Jenkins result), please execute the following command::
$ tox $ tox
After running ``tox``, the documentation will be available for viewing in HTML After running ``tox``, the documentation will be available for viewing in HTML
format in the ``doc/build/`` directory. format in the ``doc/build/`` directory.

55
specs/template.rst
View File

@@ -8,13 +8,9 @@
Example Spec - The title of your blueprint Example Spec - The title of your blueprint
========================================== ==========================================
Include the URL of your launchpad blueprint: Include the URL of your Storyboard story:
https://blueprints.launchpad.net/barbican/+spec/example https://storyboard.openstack.org/#!/story/XXXXXX
Include the URL of your client blueprint:
https://blueprints.launchpad.net/python-barbicanclient/example
Introduction paragraph -- why are we doing anything? A single paragraph of Introduction paragraph -- why are we doing anything? A single paragraph of
prose that operators can understand. prose that operators can understand.
@@ -25,10 +21,6 @@ Some notes about using this template:
* Please wrap text at 79 columns. * Please wrap text at 79 columns.
* The filename in the git repository should match the launchpad URL, for
example a URL of: https://blueprints.launchpad.net/barbican/+spec/awesome-thing
should be named awesome-thing.rst
* Please do not delete any of the sections in this template. If you have * Please do not delete any of the sections in this template. If you have
nothing to say for a whole section, just write: None nothing to say for a whole section, just write: None
@@ -108,7 +100,7 @@ Each API method which is either added or changed should have the following
* Specification for the method * Specification for the method
* A description of what the method does suitable for use in * A description of what the method does, suitable for use in
user documentation user documentation
* Method type (POST/PUT/GET/DELETE) * Method type (POST/PUT/GET/DELETE)
@@ -138,9 +130,6 @@ Each API method which is either added or changed should have the following
* Discuss any policy changes, and discuss what things a deployer needs to * Discuss any policy changes, and discuss what things a deployer needs to
think about when defining their policy. think about when defining their policy.
Example JSON schema definitions can be found in the Nova tree
https://git.openstack.org/cgit/openstack/nova/tree/nova/api/openstack/compute/schemas/v3
Note that the schema should be defined as restrictively as Note that the schema should be defined as restrictively as
possible. Parameters which are required should be marked as such and possible. Parameters which are required should be marked as such and
only under exceptional circumstances should additional parameters only under exceptional circumstances should additional parameters
@@ -196,11 +185,8 @@ the OpenStack unified clients as well as the soon to be deprecated Barbican clie
Other end user impact Other end user impact
--------------------- ---------------------
Aside from the API, are there other ways a user will interact with this Aside from the API, CLI and Python clients are there other ways a user will
feature? interact with this feature?
* Does this change have an impact on python-novaclient? What does the user
interface there look like?
Performance Impact Performance Impact
------------------ ------------------
@@ -211,16 +197,10 @@ pattern of existing code.
Examples of things to consider here include: 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 * A small change in a utility function or a commonly used decorator can have a
large impacts on performance. large impacts on performance.
* Calls which result in a database queries (whether direct or via conductor) * Calls which result in a database queries (whether direct or via barbican-worker)
can have a profound impact on performance when called in critical sections of can have a profound impact on performance when called in critical sections of
the code. the code.
@@ -234,7 +214,7 @@ Discuss things that will affect how you deploy and configure OpenStack
that have not already been mentioned, such as: that have not already been mentioned, such as:
* What config options are being added? Should they be more generic than * What config options are being added? Should they be more generic than
proposed (for example a flag that other hypervisor drivers might want to proposed (for example a flag that other Secret Stores might want to
implement as well)? Are the default values ones which will work well in implement as well)? Are the default values ones which will work well in
real deployments? real deployments?
@@ -245,11 +225,7 @@ that have not already been mentioned, such as:
* Please state anything that those doing continuous deployment, or those * Please state anything that those doing continuous deployment, or those
upgrading from the previous release, need to be aware of. Also describe upgrading from the previous release, need to be aware of. Also describe
any plans to deprecate configuration values or features. For example, if we any plans to deprecate configuration values or features.
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 Developer impact
---------------- ----------------
@@ -257,8 +233,8 @@ Developer impact
Discuss things that will affect other developers working on OpenStack, Discuss things that will affect other developers working on OpenStack,
such as: such as:
* If the blueprint proposes a change to the driver API, discussion of how * If the blueprint proposes a change to the Secrets API, discussion of how
other hypervisors would implement the feature is required. other projects might be affected.
Implementation Implementation
@@ -290,12 +266,11 @@ but we're mostly trying to understand the timeline for implementation.
Dependencies Dependencies
============ ============
* Include specific references to specs and/or blueprints in nova, or in other * Include specific references to specs and/or blueprints in barbican, or in other
projects, that this one either depends on or is related to. projects, that this one either depends on or is related to.
* If this requires functionality of another project that is not currently used * 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), by Barbican document that fact.
document that fact.
* Does this feature require any new library dependencies or code otherwise not * 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? included in OpenStack? Or does it depend on a specific version of library?
@@ -318,9 +293,9 @@ party testing, gate enhancements, etc).
Documentation Impact Documentation Impact
==================== ====================
What is the impact on the docs team of this change? Some changes might require What is the impact on the documentation of this change? Some changes might
donating resources to the docs team to have the documentation updated. Don't require a significant documentation effort. Don't repeat details discussed
repeat details discussed above, but please reference them here. above, but please reference them here.
References References