Update documentation

Update documentation to for recent changes, including
generating docs for next.json and the 1.5.json schema.
Reorganize table to content to clearly reference most
recent process documents, guidelines, and schema.

Change-Id: I9b56eecbd2e51cc7a427bddf796cc662338045d2
Partial-Bug: #1579146
This commit is contained in:
Chris Hoge 2016-06-14 17:41:26 -07:00
parent 8f9d53ecf3
commit 8c2a73327d
4 changed files with 362 additions and 13 deletions

View File

@ -2,7 +2,7 @@
OpenStack DefCore 2016.01
=========================
:Status: review
:Status: approved
:Replaces: 2015.07
:JSON Master: http://git.openstack.org/cgit/openstack/defcore/tree/2016.01.json
@ -14,7 +14,7 @@ This document was generated from the `master JSON version <2016.01.json>`_.
Releases Covered
==============================
Applies to Juno, Kilo, Liberty
Applies to Juno, Kilo, Liberty, Mitaka
Platform Components
==============================
@ -71,7 +71,6 @@ Required Capabilities
Advisory Capabilities
-----------------------
* networks-floating-ips-CRUD-and-associate (Neutron)
* networks-l3-router (Neutron)
* networks-l2-CRUD (Neutron)
* networks-l3-CRUD (Neutron)
@ -80,7 +79,6 @@ Advisory Capabilities
* images-v2-remove (Glance)
* images-v2-update (Glance)
* images-v2-share (Glance)
* images-v2-import (Glance)
* images-v2-list (Glance)
* images-v2-delete (Glance)
* images-v2-get (Glance)

View File

@ -0,0 +1,189 @@
======================
OpenStack DefCore next
======================
:Status: draft
:Replaces: 2016.01
:JSON Master: http://git.openstack.org/cgit/openstack/defcore/tree/next.json
This document outlines the mandatory capabilities and designated
sections required to exist in a software installation in order to
be eligible to use marks controlled by the OpenStack Foundation.
This document was generated from the `master JSON version <next.json>`_.
Releases Covered
==============================
Applies to Kilo, Liberty, Mitaka, Newton
Platform Components
==============================
:Required: Compute, Object
:Advisory: None
:Deprecated: None
:Removed: None
Compute Component Capabilities
==============================
Required Capabilities
-----------------------
* compute-images-create (Nova)
* compute-images-delete (Nova)
* compute-images-get (Nova)
* compute-images-list (Nova)
* compute-instance-actions-get (Nova)
* compute-instance-actions-list (Nova)
* compute-keypairs-create (Nova)
* compute-quotas-get (Nova)
* compute-servers-create (Nova)
* compute-servers-delete (Nova)
* compute-servers-get (Nova)
* compute-servers-host (Nova)
* compute-servers-invalid (Nova)
* compute-servers-list (Nova)
* compute-servers-lock (Nova)
* compute-servers-name (Nova)
* compute-servers-reboot (Nova)
* compute-servers-rebuild (Nova)
* compute-servers-resize (Nova)
* compute-servers-stop (Nova)
* compute-servers-update (Nova)
* compute-servers-verify (Nova)
* compute-volume-attach (Nova)
* compute-volume-get (Nova)
* compute-volume-list (Nova)
* compute-servers-metadata-delete (Nova)
* compute-servers-metadata-get (Nova)
* compute-servers-metadata-list (Nova)
* compute-servers-metadata-set (Nova)
* compute-servers-metadata-update (Nova)
* compute-list-api-versions (Nova)
* identity-v3-api-discovery (Keystone)
* identity-v3-tokens-create (Keystone)
* images-v2-index (Nova)
* images-v2-remove (Glance)
* images-v2-update (Glance)
* images-v2-share (Glance)
* images-v2-import (Glance)
* images-v2-list (Glance)
* images-v2-delete (Glance)
* images-v2-get (Glance)
* networks-l2-CRUD (Neutron)
* networks-security-groups-CRUD (Neutron)
* volumes-v2-create-delete (Cinder)
* volumes-v2-attach-detach (Cinder)
* volumes-v2-snapshot-create-delete (Cinder)
* volumes-v2-get (Cinder)
* volumes-v2-list (Cinder)
* volumes-v2-update (Cinder)
* volumes-v2-copy-image-to-volume (Cinder)
* volumes-v2-clone (Cinder)
* volumes-v2-availability-zones (Cinder)
* volumes-v2-extensions (Cinder)
* volumes-v2-metadata (Cinder)
* volumes-v2-reserve (Cinder)
* volumes-v2-readonly (Cinder)
Advisory Capabilities
-----------------------
* networks-l3-router (Neutron)
* networks-l3-CRUD (Neutron)
* images-v2-remove (Glance)
* images-v2-update (Glance)
* images-v2-share (Glance)
* images-v2-import (Glance)
* images-v2-list (Glance)
* images-v2-delete (Glance)
* images-v2-get (Glance)
* volumes-v2-upload (Cinder)
Deprecated Capabilities
-------------------------
* compute-auth-create (Nova)
* compute-auth-get (Nova)
* compute-auth-set (Nova)
Removed Capabilities
----------------------
* identity-v2-tokens-create (Keystone)
* compute-servers-change (Nova)
Object Component Capabilities
=============================
Required Capabilities
-----------------------
* objectstore-object-copy (Swift)
* objectstore-object-create (Swift)
* objectstore-object-delete (Swift)
* objectstore-object-get (Swift)
* objectstore-object-put (Swift)
* objectstore-object-upload (Swift)
* objectstore-object-versioned (Swift)
* objectstore-temp-url-get (Swift)
* identity-v3-tokens-create (Keystone)
Advisory Capabilities
-----------------------
* objectstore-account-quotas (Swift)
* objectstore-account-list (Swift)
* objectstore-container-acl (Swift)
* objectstore-container-quotas (Swift)
* objectstore-container-create (Swift)
* objectstore-container-delete (Swift)
* objectstore-container-list (Swift)
Deprecated Capabilities
-------------------------
* objectstore-object-access (Swift)
Removed Capabilities
----------------------
* identity-v2-tokens-create (Keystone)
Designated Sections
=====================================
The following designated sections apply to the same releases as
this specification.
Required Designated Sections
----------------------------
* Cinder : Designated sections are the API implementation code
* Glance : Designated sections are the API implementation code and domain
model.
* Keystone : Designation is outlined per API grouping. Identity (user and
group) management APIs will not be designated. API access (with exception of
auth) may be prohibited by policy (resulting in HTTP 403). Designated APIs
include both v2.0 and v3 versions where applicable.
* Nova : By default, designated except scheduler, filter, drivers, API
extensions and networking.
* Swift : Designated sections are proxy server, object server, container
server, account server and select middleware
Advisory Designated Sections
----------------------------
* Neutron : By default, designated for all code backing required capabilities
except plugable components such as plugins, drivers, and API extensions other
than those listed below.
Deprecated Designated Sections
------------------------------
None
Removed Designated Sections
---------------------------
None

View File

@ -7,27 +7,45 @@ Process Documentation
=====================
.. toctree::
:glob:
:maxdepth: 1
process/*
process/2016A.rst
=====================
Schema Documentation
=====================
.. toctree::
:glob:
:maxdepth: 1
schema/*
schema/1.5.rst
==========
Guidelines
==========
=================
Active Guidelines
=================
.. toctree::
:glob:
:maxdepth: 1
guidelines/*
guidelines/2015.07.rst
guidelines/2016.01.rst
==================
Proposed Guideline
==================
.. toctree::
:maxdepth: 1
guidelines/next.rst
===================
Inactive Guidelines
===================
.. toctree::
:maxdepth: 1
guidelines/2015.03.rst
guidelines/2015.04.rst
guidelines/2015.05.rst

144
doc/source/schema/1.5.rst Normal file
View File

@ -0,0 +1,144 @@
DefCore Schema v1.5 Change Log
==============================
Changes from v1.4
:change: move to formal json schema.
Changes from v1.3
:change: update the aliases field description
:added: aliases field in test block
:added: cutoff_score
:added: target_approval
:removed: Status field in Capability blocks (as it duplicates the information
already present in the Components list)
Changes from v1.2
:added: reference
:added: tests-repositories
:added: required-since
:added: tests now have block including idempotent_id and (optional) flagged
information
:change: guidelines to point to required-since
:change: tests from array to hash
:change: add hash after test-name keys
:change: flagged points to new location tests/test-name/flagged
:change: new version 1.3
Annotated Sample
================
Schema sample and annotations for reference only. Full schema
follows.
.. code-block:: json
{ "id": "2016.01", # Spec name (date based)
"schema": "1.5", # Schema version
"reference": "http://github.com/openstack/defcore/schema.1.4.rst",
# Schema description
"source": "http://git.openstack.org/cgit/openstack/defcore/",
# git repo for files
"status": "approved", # can be draft, review, approved or superseded [see 2015B C6.3]
"cutoff_score": "74", # the minimum score a Capability must achieve to be required in this Guideline
"target_approval": "2016-01-27",
# Target date for BoD to approve Guideline
"replaces": "2015.07", # previous spec
"releases": ["icehouse"], # array of releases, lower case (generally three releases)
"platform": { # platform components
"required": [ # required component array
"compute", "object"
],
"advisory": [], # incoming component array
"deprecated": [], # outgoing component array
"removed": [] # removed component array
},
"components": { # components detail
"compute": { # component name
"required": [ # required component array
"compute-auth"
],
"advisory": [ # incoming component array
"compute-servers-metadata"
],
"deprecated": [], # outgoing component array
"removed": [ # removed component array
"volume"
]
},
},
"test-repositories": { # tracks difference possible test sources
"tempest": { # source of tests
"git-sha": "c77e46d8e3",
# reference sha for automated checkout of known working release
"url": "https://git.openstack.org/cgit/openstack/tempest/"
# repository location
}
},
"criteria" : { # explains achievements
"core01" : {
"Description" : "blah blah blah",
"name" : "readable core01",
# allows more readable name than key
"weight": 8 # total of all weights must be 100
},
}
"capabilities": { # capabilities listed in components
"example-cap" : { # capability key (cross reference to components required)
"achievements" : ["core01"],
# array of criteria met. must be one of items from "criteria" section
"admin" : false, # boolean designating whether an admin API is required
"required-since" : "2015.05"
# guideline where capability became required, "" if not required
"description" : "Helpful Description",
"name" : "Friendly Short Name",
"tests" : { # hash of tests (use unique names)
"tempest.api.project.file.class.test_name" : {
# test ID
"idempotent_id" : "id-123-456", # internal test identifier to track changes if test is moved
"aliases" : [], # A list of other names used to identify the same test, as sometimes
# test names change due to refactoring in Tempest. The name used as
# the key in the hash should be the name of the test as it was at the
# time the guideline was approved. Thus if this is a future guideline,
# move the old name here and put the new name as the hash key. If this
# is an approved guideline, then the new name goes in this list.
"flagged" : { # This section is required only if the test is flagged
"reason" : "why this test was flagged",
# required to support flag request
"action" : "proposed action to resolve",
# required path to resolve flag
"date" : "yyyy-mm-dd"
# date flag was proposed (not approved)
}
},
},
},
},
"designated-sections" : { # designated sections
"required" : { # sections that are required for this Guideline
"nova" : { # project name
"guidance": "short description", # general information providing actionable detail
"comment": "optional rationale", # additional clairification
"sections": { # hash of sections, project specific
"section": { # key / name of a section
"description": "useful detail", # expand on key in useful way
"designated": false, # boolean. true if designated. must align with guidance
"comment": "none provided" # optional details
}
}
}
},
"advisory" : {}, # not required in this Guideline but may be required in a future guideline
"deprecated" : {}, # no longer required in this Guideline and will be removed in futur Guidelines
"removed" : {} # no longer required and have been removed since the last Guideline
}
}
JSON Schema Definition
======================
.. literalinclude:: 1.5.json