Update sphinx doc formatting and toctrees

Create index pages with toctree entries to load the existing
documents so they are all linked together.

Add titles to some of the documents that did not have them to
make them work with sphinx.

Change-Id: I0d44cfe1a75ab7df07e0efc989eb7cf161d9bf78
This commit is contained in:
Doug Hellmann 2014-04-30 13:30:36 -04:00
parent 521183d05a
commit 37178d955d
14 changed files with 262 additions and 152 deletions

4
.gitignore vendored Normal file
View File

@ -0,0 +1,4 @@
.tox
doc/build
*.egg-info
pbr*.egg

View File

View File

@ -1 +0,0 @@
../../README.rst

19
doc/source/index.rst Normal file
View File

@ -0,0 +1,19 @@
====================================================
OpenStack Technical Committee Governance Documents
====================================================
These pages contain OpenStack Technical Committee reference documents
and track official resolutions voted by the committee.
.. toctree::
:maxdepth: 2
:glob:
reference/index
resolutions/index
.. seealso::
See the TechnicalCommittee_ page in the wiki for details.
.. _TechnicalCommittee: https://wiki.openstack.org/wiki/Governance/TechnicalCommittee

View File

@ -1 +1 @@
../../reference/
../../reference

1
doc/source/resolutions Symbolic link
View File

@ -0,0 +1 @@
../../resolutions

View File

@ -1,6 +1,6 @@
=========================================
OpenStack Technical Committee charter
=========================================
=======================================
OpenStack Technical Committee Charter
=======================================
Mission
=======

View File

@ -1,145 +0,0 @@
= Minimal requirements for incubation and integrated status =
== Incubation ==
The TC will evaluate the project scope and its complementarity with existing
integrated projects and other official programs, look into the project
technical choices, and check a number of requirements, including (but not
limited to):
* Scope
** Project must have a clear and defined scope.
** Project's scope should represent a measured progression for OpenStack as a
whole.
** Project should not inadvertently duplicate functionality present in other
OpenStack projects. If they do, they should have a clear plan and timeframe
to prevent long-term scope duplication.
** Project should leverage existing functionality in other OpenStack projects
as much as possible
* Maturity
** Project should have an active team of contributors
** Project should not have a major architectural rewrite planned
* Process
** Project must be hosted under stackforge (and therefore use git as its VCS)
** Project must obey OpenStack coordinated project interface (such as tox,
pbr, global-requirements...)
** Project should use oslo libraries or oslo-incubator where appropriate
** If project is not part of an existing program, it needs to file for a new
program concurrently with the Incubation request, and fill the corresponding
requirements.
** Project must have a well-defined core review team, with reviews distributed
amongst the team (and not being primarily done by one person)
** Reviews should follow the same criteria as OpenStack projects (2 +2s
before +A)
** Project should use the official openstack lists for discussion
* API
** Project APIs should be reasonably stable
** Project must have a REST API with at least a JSON entity representation
** Project must have a Python client library API for its REST API
* QA
** Project must have a basic devstack-gate job set up
* Documentation / User support
** Project must have docs for developers who want to contribute to the project
** Project should have API documentation for devs who want to add to the API,
updated when the code is updated
* Legal requirements
** Project must be licensed under the Apache License v2
** Project must have no library dependencies which effectively restrict how
the project may be distributed or deployed [1]
** All contributors to the project must have signed the CLA
** Project must have no known trademark issues [2]
[1] https://wiki.openstack.org/wiki/LegalIssuesFAQ#Licensing_of_library_dependencies
[2] https://wiki.openstack.org/wiki/LegalIssuesFAQ#New_Project_Names
= Graduation to integrated =
At the end of every cycle, incubated projects go through a graduation review
to check if they are ready to be made an integral part of the next development
cycle and be included in the next OpenStack integrated release. The TC will
evaluate the technical maturity of the project and check a number of
requirements, including (but not limited to):
* Scope
** Project must not duplicate functionality present in other OpenStack projects,
unless the project has intentionally done so with the intent of replacing it.
** In the case that a project has intentionally duplicated functionality of
another project, or portion of a project, the new project must reach a level
of functionality and maturity such that we are ready to deprecate the old
code and remove it after a well defined deprecation cycle. The deprecation
plan agreed to by the PTLs of each affected project, including details for
how users will be able to migrate from the old to the new, must be submitted
to the TC for review as a part of the graduation review.
* Maturity
** Project must have a large and diverse team of contributors
** Project must have completed integration work with other integrated
projects, as communicated by the TC when accepted into incubation (that
includes Dashboard integration if applicable)
* Process
** Project must have a diverse core reviewers team (more than 4 people)
** Core reviewers must enforce a minimum of 2 +2s before accepting a change
** Project should have engaged with marketing team to check suitable official
name
** Project must use OpenStack task, defect and design tracker(s)
* QA
** Project must have a devstack-gate job running. This gate job should install
the project using devstack and then run tempest tests. This job should run
and vote in the check and gate pipelines for the project. It is *not* required
that this job is running for the projects it depends on. This demonstrates
that it would be easy to add the project to the integrated gate after
graduation.
** Project must have decent unit test and functional tests coverage
** Project must be compatible with all currently OpenStack-supported versions
of Python
** Project should have a decent record of triaging incoming bugs
* Documentation / User support
** Project must have end-user docs such as API use, CLI use, Dashboard use
** Project should have installation docs providing install/deployment in an
integrated manner similar to other OpenStack projects, including
configuration reference information for all options
** Project should have a proven history of providing user support (on the
openstack@ mailing list and on Ask OpenStack)
* Release management / Security
** Project must have followed at least two common milestones (follow the common
cycle at least since X-2)
** Project must have had at least one of their milestones handled by the
release management team (at least the X-3 milestone)
** Project must provide a 2+ person team that will handle the project specific
vulnerability process [3]
[3] https://wiki.openstack.org/wiki/Vulnerability_Management
= First Integrated Cycle Expectations =
In the release cycle after the project has graduated, the TC expects the project
to reach a level of maturity for its first integrated release. In order for the
project to graduate, the TC will need to be confident that the project will
reach that level of maturity in the time allowed.
* API
** The REST API must be declared stable and the project must commit to
maintaining backwards compatibility
** If the project has resources which would make sense to provision
via a Heat template, then the project should have Heat integration
which enables this
** If the project has functionality which would make sense to be
available in the Horizon dashboard, then the project should ensure
that integration exists
* QA
** The project should prepare upgrade testing (currently grenade) during
the first integrated cycle so that it is ready to enable upgrade testing
jobs shortly after its first integrated release.

View File

@ -0,0 +1,180 @@
===========================================================
Minimal Requirements for Incubation and Integrated Status
===========================================================
Incubation
==========
The TC will evaluate the project scope and its complementarity with existing
integrated projects and other official programs, look into the project
technical choices, and check a number of requirements, including (but not
limited to):
Scope
-----
* Project must have a clear and defined scope.
* Project's scope should represent a measured progression for OpenStack as a
whole.
* Project should not inadvertently duplicate functionality present in other
OpenStack projects. If they do, they should have a clear plan and timeframe
to prevent long-term scope duplication.
* Project should leverage existing functionality in other OpenStack projects
as much as possible
Maturity
--------
* Project should have an active team of contributors
* Project should not have a major architectural rewrite planned
Process
-------
* Project must be hosted under stackforge (and therefore use git as its VCS)
* Project must obey OpenStack coordinated project interface (such as tox,
pbr, global-requirements...)
* Project should use oslo libraries or oslo-incubator where appropriate
* If project is not part of an existing program, it needs to file for a new
program concurrently with the Incubation request, and fill the corresponding
requirements.
* Project must have a well-defined core review team, with reviews distributed
amongst the team (and not being primarily done by one person)
* Reviews should follow the same criteria as OpenStack projects (2 +2s
before +A)
* Project should use the official openstack lists for discussion
API
---
* Project APIs should be reasonably stable
* Project must have a REST API with at least a JSON entity representation
* Project must have a Python client library API for its REST API
QA
--
* Project must have a basic devstack-gate job set up
Documentation / User support
----------------------------
* Project must have docs for developers who want to contribute to the project
* Project should have API documentation for devs who want to add to the API,
updated when the code is updated
Legal requirements
------------------
* Project must be licensed under the Apache License v2
* Project must have no library dependencies which effectively restrict how
the project may be distributed or deployed [1]_
* All contributors to the project must have signed the CLA
* Project must have no known trademark issues [2]_
.. [1] https://wiki.openstack.org/wiki/LegalIssuesFAQ#Licensing_of_library_dependencies
.. [2] https://wiki.openstack.org/wiki/LegalIssuesFAQ#New_Project_Names
Graduation to integrated
========================
At the end of every cycle, incubated projects go through a graduation review
to check if they are ready to be made an integral part of the next development
cycle and be included in the next OpenStack integrated release. The TC will
evaluate the technical maturity of the project and check a number of
requirements, including (but not limited to):
Scope
-----
* Project must not duplicate functionality present in other OpenStack projects,
unless the project has intentionally done so with the intent of replacing it.
* In the case that a project has intentionally duplicated functionality of
another project, or portion of a project, the new project must reach a level
of functionality and maturity such that we are ready to deprecate the old
code and remove it after a well defined deprecation cycle. The deprecation
plan agreed to by the PTLs of each affected project, including details for
how users will be able to migrate from the old to the new, must be submitted
to the TC for review as a part of the graduation review.
Maturity
--------
* Project must have a large and diverse team of contributors
* Project must have completed integration work with other integrated
projects, as communicated by the TC when accepted into incubation (that
includes Dashboard integration if applicable)
Process
-------
* Project must have a diverse core reviewers team (more than 4 people)
* Core reviewers must enforce a minimum of 2 +2s before accepting a change
* Project should have engaged with marketing team to check suitable official
name
* Project must use OpenStack task, defect and design tracker(s)
QA
--
* Project must have a devstack-gate job running. This gate job should install
the project using devstack and then run tempest tests. This job should run
and vote in the check and gate pipelines for the project. It is*not* required
that this job is running for the projects it depends on. This demonstrates
that it would be easy to add the project to the integrated gate after
graduation.
* Project must have decent unit test and functional tests coverage
* Project must be compatible with all currently OpenStack-supported versions
of Python
* Project should have a decent record of triaging incoming bugs
Documentation / User support
----------------------------
* Project must have end-user docs such as API use, CLI use, Dashboard use
* Project should have installation docs providing install/deployment in an
integrated manner similar to other OpenStack projects, including
configuration reference information for all options
* Project should have a proven history of providing user support (on the
openstack@ mailing list and on Ask OpenStack)
Release management / Security
-----------------------------
* Project must have followed at least two common milestones (follow the common
cycle at least since X-2)
* Project must have had at least one of their milestones handled by the
release management team (at least the X-3 milestone)
* Project must provide a 2+ person team that will handle the project specific
vulnerability process [3]_
.. [3] https://wiki.openstack.org/wiki/Vulnerability_Management
First Integrated Cycle Expectations
===================================
In the release cycle after the project has graduated, the TC expects the project
to reach a level of maturity for its first integrated release. In order for the
project to graduate, the TC will need to be confident that the project will
reach that level of maturity in the time allowed.
API
---
* The REST API must be declared stable and the project must commit to
maintaining backwards compatibility
* If the project has resources which would make sense to provision
via a Heat template, then the project should have Heat integration
which enables this
* If the project has functionality which would make sense to be
available in the Horizon dashboard, then the project should ensure
that integration exists
QA
--
* The project should prepare upgrade testing (currently grenade) during
the first integrated cycle so that it is ready to enable upgrade testing
jobs shortly after its first integrated release.

14
reference/index.rst Normal file
View File

@ -0,0 +1,14 @@
==========================================
OpenStack Technical Committee References
==========================================
Reference documents which need to be revised over time.
.. toctree::
:maxdepth: 2
:glob:
charter
new-programs-requirements
incubation-integration-requirements

View File

@ -1,5 +1,5 @@
======================================================
Minimal requirements for new programs applications
Minimal Requirements for New Programs Applications
======================================================
Teams in OpenStack can be created as-needed and grow organically. As the team

View File

@ -1,3 +1,7 @@
===============================================
2013-31-06 Ceilometer and Heat Official Names
===============================================
The OpenStack Foundation bylaws state:
https://wiki.openstack.org/wiki/Governance/Foundation/Bylaws

View File

@ -1,3 +1,7 @@
=============================
2014-02-11 DefCore Response
=============================
This resolution is the draft of an email from the TC to the Board DefCore
committee on the issue of identifying "required sections" of code.

View File

@ -1,12 +1,18 @@
===================================================
2014-04-02 DefCore Designated Sections Guidelines
===================================================
This resolution is about formally approving the general selection principles
for "designated sections" of code, as part of the DefCore effort.
Sections of code should generally be DESIGNATED when:
- code provides the project external REST API, or
- code is shared and provides common functionality for all options, or
- code implements logic that is critical for cross-platform operation
Sections of code should generally NOT be DESIGNATED when:
- code interfaces to vendor-specific functions, or
- project design explicitly intended this section to be replaceable, or
- code extends the project external REST API in a new or different way, or

24
resolutions/index.rst Normal file
View File

@ -0,0 +1,24 @@
=============
Resolutions
=============
When a motion does not result in a change in a reference doc, it can
be expressed as a resolution.
2014
====
.. toctree::
:maxdepth: 1
:glob:
2014*
2013
====
.. toctree::
:maxdepth: 1
:glob:
2013*