Merge "[contributor] reorganize blueprints and specifications"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
adaaf0ff76
|
|
@ -1,16 +1,22 @@
|
|||
=============================
|
||||
Blueprints and specifications
|
||||
=============================
|
||||
.. _content-specs:
|
||||
|
||||
The Documentation team uses specifications in the `docs-specs repository`_ to
|
||||
maintain large changes. Approved specifications are published at
|
||||
`Documentation Program Specifications`_. For tracking purposes, a blueprint is
|
||||
created for each specification.
|
||||
=====================
|
||||
Content specification
|
||||
=====================
|
||||
|
||||
Blueprints and specifications
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Documentation team uses specifications in the `docs-specs repository
|
||||
<http://git.openstack.org/cgit/openstack/docs-specs>`_ to maintain large
|
||||
changes. Approved specifications are published at `Documentation Program
|
||||
Specifications <http://specs.openstack.org/openstack/docs-specs>`_.
|
||||
For tracking purposes, a blueprint is created for each specification.
|
||||
|
||||
Use blueprints and specifications:
|
||||
|
||||
* When adding large sections to an existing document to ensure involvement of
|
||||
the core doc team.
|
||||
* When adding large sections to an existing document to ensure involvement
|
||||
of the docs core team.
|
||||
* When adding an entirely new deliverable to the docs project.
|
||||
* For any work that requires both content and tooling changes, such as
|
||||
addition of the API reference site.
|
||||
|
|
@ -18,9 +24,11 @@ Use blueprints and specifications:
|
|||
* For automation work that needs to be designed prior to proposing a patch.
|
||||
* For work that should definitely be discussed at a summit.
|
||||
|
||||
A specification needs two +2 votes from the docs-specs-core team. See the
|
||||
current list of `docs-specs core team`_. For more information, see:
|
||||
`Blueprints and specifications`_.
|
||||
A specification needs two +2 votes from the docs-specs-core team.
|
||||
See the current list of `docs-specs core team
|
||||
<https://review.openstack.org/#/admin/groups/384,members>`_.
|
||||
For more information, see `Blueprints and specifications
|
||||
<https://wiki.openstack.org/wiki/Blueprints#Blueprints_and_Specs>`_.
|
||||
|
||||
Use bugs against openstack-manuals or openstack-api-site:
|
||||
|
||||
|
|
@ -29,10 +37,163 @@ Use bugs against openstack-manuals or openstack-api-site:
|
|||
* To add content that is just missing.
|
||||
* For known errors in a document.
|
||||
|
||||
For more information, see: :ref:`doc_bugs`.
|
||||
For more information, see :ref:`doc_bugs`.
|
||||
|
||||
.. Links
|
||||
.. _`docs-specs repository`: http://git.openstack.org/cgit/openstack/docs-specs/
|
||||
.. _`Documentation Program Specifications`: http://specs.openstack.org/openstack/docs-specs/
|
||||
.. _`docs-specs core team`: https://review.openstack.org/#/admin/groups/384,members
|
||||
.. _`Blueprints and specifications`: https://wiki.openstack.org/wiki/Blueprints#Blueprints_and_Specs
|
||||
Release-specific documentation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Installation Guides, Configuration Reference, and Networking Guide
|
||||
are released at release time, with draft material published to
|
||||
https://docs.openstack.org/draft/draft-index.html.
|
||||
The rest of the guides are continuously released.
|
||||
|
||||
To patch for the release-specific documentation, you should generally patch to
|
||||
master branch with "backport: xxxx" (for example, backport: kilo) in the commit
|
||||
message.
|
||||
|
||||
Installation Guides
|
||||
-------------------
|
||||
|
||||
The OpenStack Installation Guide describes a manual install process for
|
||||
multiple distributions based on the following packaging systems:
|
||||
|
||||
* `Installation Guide for openSUSE and SUSE Linux Enterprise Server
|
||||
<http://docs.openstack.org/mitaka/install-guide-obs/>`_
|
||||
* `Installation Guide for Red Hat Enterprise Linux and CentOS
|
||||
<http://docs.openstack.org/mitaka/install-guide-rdo/>`_
|
||||
* `Installation Guide for Ubuntu
|
||||
<http://docs.openstack.org/mitaka/install-guide-ubuntu/>`_
|
||||
|
||||
Guides for deployers and administrators
|
||||
---------------------------------------
|
||||
|
||||
* `OpenStack Configuration Reference
|
||||
<http://docs.openstack.org/mitaka/config-reference/>`_:
|
||||
Contains a reference listing of all configuration options for OpenStack
|
||||
services by release version.
|
||||
* `OpenStack Networking Guide
|
||||
<http://docs.openstack.org/mitaka/networking-guide/>`_:
|
||||
This guide targets OpenStack administrators seeking to deploy and manage
|
||||
OpenStack Networking (neutron).
|
||||
|
||||
Continuously released documentation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
These guides cover multiple versions and we follow the general
|
||||
`release information <https://wiki.openstack.org/wiki/Releases>`_.
|
||||
The guides cover the latest two versions, for
|
||||
example Juno and Kilo. The following exceptions apply:
|
||||
|
||||
* Operations Guide: Icehouse target, revised specifically to target that
|
||||
release
|
||||
* HA Guide: Updated last at Havana timeframe, still needs updates
|
||||
|
||||
Guides for deployers and administrators
|
||||
---------------------------------------
|
||||
|
||||
* `OpenStack Architecture Design Guide
|
||||
<http://docs.openstack.org/arch-design/>`_:
|
||||
Contains information on how to plan, design and architect
|
||||
an OpenStack cloud.
|
||||
* `OpenStack Administrator Guide <http://docs.openstack.org/admin-guide/>`_:
|
||||
Contains how-to information for managing an OpenStack cloud as needed for
|
||||
your use cases, such as storage, computing, or software-defined-networking.
|
||||
* `OpenStack High Availability Guide <http://docs.openstack.org/ha-guide/>`_:
|
||||
Describes potential strategies for making your OpenStack services and
|
||||
related controllers and data stores highly available.
|
||||
* `OpenStack Security Guide <http://docs.openstack.org/sec>`_:
|
||||
Provide best practices and conceptual
|
||||
information about securing an OpenStack cloud.
|
||||
* `Virtual Machine Image Guide <http://docs.openstack.org/image-guide>`_:
|
||||
Shows you how to obtain, create, and modify virtual machine images that
|
||||
are compatible with OpenStack.
|
||||
|
||||
Guides for end users
|
||||
--------------------
|
||||
|
||||
* `OpenStack End User Guide <http://docs.openstack.org/user-guide/>`_:
|
||||
Shows OpenStack end users how to create and manage resources in an
|
||||
OpenStack cloud with the OpenStack dashboard and OpenStack client commands.
|
||||
* `OpenStack API Guide
|
||||
<http://developer.openstack.org/api-guide/quick-start/>`_:
|
||||
A brief overview of how to send REST API requests to endpoints for
|
||||
OpenStack services.
|
||||
* `OpenStack Command-Line Interface Reference
|
||||
<http://docs.openstack.org/cli-reference/>`_:
|
||||
Automatically generates help text for CLI commands and subcommands.
|
||||
|
||||
API documentation
|
||||
-----------------
|
||||
|
||||
* `Complete API Reference <http://developer.openstack.org/api-ref.html>`_:
|
||||
Complete reference listing of OpenStack REST APIs
|
||||
with example requests and responses.
|
||||
* `API specifications <http://specs.openstack.org/>`_:
|
||||
Within project's specification repos, some have opted
|
||||
to document API specifications, such as Identity.
|
||||
* `Object Storage API v1
|
||||
<http://docs.openstack.org/developer/swift/#object-storage-v1-rest-api-documentation>`_
|
||||
|
||||
Guides for contributors
|
||||
-----------------------
|
||||
|
||||
* `Infrastructure User Manual <http://docs.openstack.org/infra/manual>`_:
|
||||
Reference documentation for tools and processes used for all
|
||||
contributors to OpenStack projects. It includes instructions on how
|
||||
to create all the necessary accounts, setup development environment,
|
||||
use gerrit review workflow. The manual also covers more
|
||||
advanced topics, like how to create new git repositories. The manual is
|
||||
maintained by the OpenStack Infrastructure team.
|
||||
|
||||
Licenses
|
||||
~~~~~~~~
|
||||
|
||||
This section shows the license indicators as of March 20, 2015.
|
||||
|
||||
* OpenStack Architecture Design Guide: Apache 2.0 and CC-by-sa 3.0
|
||||
* OpenStack Administrator Guide: Apache 2.0 and CC-by-sa 3.0
|
||||
|
||||
* OpenStack Install Guides (all): Apache 2.0
|
||||
* OpenStack High Availability Guide: Apache 2.0
|
||||
* OpenStack Configuration Reference: Apache 2.0
|
||||
* OpenStack Networking Guide: Apache 2.0
|
||||
|
||||
* OpenStack Security Guide: CC-by 3.0
|
||||
* Virtual Machine Image Guide: CC-by 3.0
|
||||
* OpenStack Operations Guide: CC-by 3.0
|
||||
* OpenStack End User Guide: CC-by 3.0
|
||||
* Command-Line Interface Reference: CC-by 3.0
|
||||
|
||||
* Contributor dev docs (docs.openstack.org/developer/<projectname>): none
|
||||
indicated in output; Apache 2.0 in repo
|
||||
* OpenStack API Quick Start: none indicated in output; Apache 2.0 in repo
|
||||
* API Complete Reference: none indicated in output; Apache 2.0 in repo
|
||||
|
||||
* Infrastructure User Manual: none indicated in output; CC-by 3.0 in repo
|
||||
|
||||
What to do to make more consistent output:
|
||||
|
||||
* OpenStack Architecture Design Guide: Apache 2.0 and CC-by 3.0
|
||||
* OpenStack Administrator Guide: Apache 2.0 and CC-by 3.0
|
||||
* OpenStack Install Guides (all): Apache 2.0 and CC-by 3.0
|
||||
* OpenStack High Availability Guide: Apache 2.0 and CC-by 3.0
|
||||
* OpenStack Security Guide: CC-by 3.0
|
||||
* Virtual Machine Image Guide: CC-by 3.0
|
||||
* OpenStack Operations Guide: CC-by 3.0
|
||||
* OpenStack End User Guide: CC-by 3.0
|
||||
|
||||
These guides are created by "scraping" code:
|
||||
|
||||
* OpenStack Configuration Reference: Apache 2.0 and CC-by 3.0
|
||||
* Command-Line Interface Reference: Apache 2.0 and CC-by 3.0
|
||||
|
||||
These guides have no indicator in output:
|
||||
|
||||
* Contributor dev docs (docs.openstack.org/developer/<projectname>): none
|
||||
indicated in output; Apache 2.0 in repo
|
||||
* OpenStack API Quick Start: none indicated in output; Apache 2.0 in repo
|
||||
* API Complete Reference: none indicated in output; Apache 2.0 in repo
|
||||
|
||||
This guide has a review in place to get a license indicator in output:
|
||||
|
||||
* Infrastructure User Manual: none indicated in output; CC-by 3.0 in repo
|
||||
|
|
|
|||
|
|
@ -1,175 +0,0 @@
|
|||
|
||||
.. _content-specs:
|
||||
|
||||
=====================
|
||||
Content specification
|
||||
=====================
|
||||
|
||||
Release-specific documentation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Installation Guides, Configuration Reference, and Networking Guide
|
||||
are released at release time, with draft material published to
|
||||
docs.openstack.org/draft/draft-index.html. The rest of the guides are
|
||||
continuously released.
|
||||
|
||||
To patch for the release-specific documentation, you should generally patch to
|
||||
master branch with "backport: xxxx" (for example, backport: kilo) in the commit
|
||||
message.
|
||||
|
||||
Installation Guides
|
||||
-------------------
|
||||
|
||||
The OpenStack Installation Guide describes a manual install process for
|
||||
multiple distributions based on the following packaging systems:
|
||||
|
||||
* `Installation Guide for openSUSE and SUSE Linux Enterprise Server`_
|
||||
* `Installation Guide for Red Hat Enterprise Linux and CentOS`_
|
||||
* `Installation Guide for Ubuntu`_
|
||||
|
||||
Guides for deployers and administrators
|
||||
---------------------------------------
|
||||
|
||||
* `OpenStack Configuration Reference`_: Contains a reference listing of all
|
||||
configuration options for core and integrated OpenStack services by release
|
||||
version.
|
||||
* `OpenStack Networking Guide`_: This guide targets OpenStack administrators
|
||||
seeking to deploy and manage OpenStack Networking (neutron).
|
||||
|
||||
Continuously released documentation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
These guides cover multiple versions and we follow the general
|
||||
`release information`_. The guides cover the latest two versions, for
|
||||
example Juno and Kilo. The following exceptions apply:
|
||||
|
||||
* Operations Guide: Icehouse target, revised specifically to target that
|
||||
release
|
||||
* HA Guide: Updated last at Havana timeframe, still needs updates
|
||||
|
||||
Guides for deployers and administrators
|
||||
---------------------------------------
|
||||
|
||||
* `OpenStack Architecture Design Guide`_: Contains information on how to plan,
|
||||
design and architect an OpenStack cloud.
|
||||
* `OpenStack Administrator Guide`_: Contains how-to information for
|
||||
managing an OpenStack cloud as needed for your use cases, such as storage,
|
||||
computing, or software-defined-networking.
|
||||
* `OpenStack High Availability Guide`_: Describes potential strategies for
|
||||
making your OpenStack services and related controllers and data stores
|
||||
highly available.
|
||||
* `OpenStack Security Guide`_: Provide best practices and conceptual
|
||||
information about securing an OpenStack cloud.
|
||||
* `Virtual Machine Image Guide`_: Shows you how to obtain, create, and modify
|
||||
virtual machine images that are compatible with OpenStack.
|
||||
|
||||
Guides for end users
|
||||
--------------------
|
||||
|
||||
* `OpenStack End User Guide`_: Shows OpenStack end users how to create and
|
||||
manage resources in an OpenStack cloud with the OpenStack dashboard and
|
||||
OpenStack client commands.
|
||||
* `OpenStack API Guide`_: A brief overview of how to send REST API
|
||||
requests to endpoints for OpenStack services.
|
||||
* `Command-Line Interface Reference`_: Automatically generates help text for
|
||||
CLI commands and subcommands.
|
||||
|
||||
API documentation
|
||||
-----------------
|
||||
|
||||
* `Complete API Reference`_: Complete reference listing of OpenStack REST APIs
|
||||
with example requests and responses.
|
||||
* `API specifications`_: Within project's specification repos, some have opted
|
||||
to document API specifications, such as Identity.
|
||||
* `Object Storage API v1`_
|
||||
|
||||
Guides for contributors
|
||||
-----------------------
|
||||
|
||||
* `Infrastructure User Manual`_: Reference documentation for tools and
|
||||
processes used for all contributors to OpenStack projects. It includes
|
||||
instructions on how to create all the necessary accounts, setup development
|
||||
environment, use gerrit review workflow. The manual also covers more
|
||||
advanced topics, like how to create new git repositories. The manual is
|
||||
maintained by the OpenStack Infrastructure team.
|
||||
|
||||
Licenses
|
||||
--------
|
||||
|
||||
This section shows the license indicators as of March 20, 2015.
|
||||
|
||||
* OpenStack Architecture Design Guide: Apache 2.0 and CC-by-sa 3.0
|
||||
* OpenStack Administrator Guide: Apache 2.0 and CC-by-sa 3.0
|
||||
|
||||
* OpenStack Install Guides (all): Apache 2.0
|
||||
* OpenStack High Availability Guide: Apache 2.0
|
||||
* OpenStack Configuration Reference: Apache 2.0
|
||||
* OpenStack Networking Guide: Apache 2.0
|
||||
|
||||
* OpenStack Security Guide: CC-by 3.0
|
||||
* Virtual Machine Image Guide: CC-by 3.0
|
||||
* OpenStack Operations Guide: CC-by 3.0
|
||||
* OpenStack End User Guide: CC-by 3.0
|
||||
* Command-Line Interface Reference: CC-by 3.0
|
||||
|
||||
* Contributor dev docs (docs.openstack.org/developer/<projectname>): none
|
||||
indicated in output; Apache 2.0 in repo
|
||||
* OpenStack API Quick Start: none indicated in output; Apache 2.0 in repo
|
||||
* API Complete Reference: none indicated in output; Apache 2.0 in repo
|
||||
|
||||
* Infrastructure User Manual: none indicated in output; CC-by 3.0 in repo
|
||||
|
||||
What to do to make more consistent output:
|
||||
|
||||
* OpenStack Architecture Design Guide: Apache 2.0 and CC-by 3.0
|
||||
* OpenStack Administrator Guide: Apache 2.0 and CC-by 3.0
|
||||
* OpenStack Install Guides (all): Apache 2.0 and CC-by 3.0
|
||||
* OpenStack High Availability Guide: Apache 2.0 and CC-by 3.0
|
||||
* OpenStack Security Guide: CC-by 3.0
|
||||
* Virtual Machine Image Guide: CC-by 3.0
|
||||
* OpenStack Operations Guide: CC-by 3.0
|
||||
* OpenStack End User Guide: CC-by 3.0
|
||||
|
||||
These guides are created by "scraping" code:
|
||||
|
||||
* OpenStack Configuration Reference: Apache 2.0 and CC-by 3.0
|
||||
* Command-Line Interface Reference: Apache 2.0 and CC-by 3.0
|
||||
|
||||
These guides have no indicator in output:
|
||||
|
||||
* Contributor dev docs (docs.openstack.org/developer/<projectname>): none
|
||||
indicated in output; Apache 2.0 in repo
|
||||
* OpenStack API Quick Start: none indicated in output; Apache 2.0 in repo
|
||||
* API Complete Reference: none indicated in output; Apache 2.0 in repo
|
||||
|
||||
This guide has a review in place to get a license indicator in output:
|
||||
|
||||
* Infrastructure User Manual: none indicated in output; CC-by 3.0 in repo
|
||||
|
||||
|
||||
.. Links
|
||||
.. _`Installation Guide for openSUSE and SUSE Linux Enterprise Server`: http://docs.openstack.org/mitaka/install-guide-obs/
|
||||
.. _`Installation Guide for Red Hat Enterprise Linux and CentOS`: http://docs.openstack.org/mitaka/install-guide-rdo/
|
||||
.. _`Installation Guide for Ubuntu`: http://docs.openstack.org/mitaka/install-guide-ubuntu/
|
||||
|
||||
.. _`OpenStack Configuration Reference`: http://docs.openstack.org/mitaka/config-reference/
|
||||
|
||||
.. _`OpenStack Networking Guide`: http://docs.openstack.org/mitaka/networking-guide/
|
||||
|
||||
.. _`release information`: https://wiki.openstack.org/wiki/Releases
|
||||
|
||||
.. _`OpenStack Architecture Design Guide`: http://docs.openstack.org/arch-design/
|
||||
.. _`OpenStack Administrator Guide`: http://docs.openstack.org/admin-guide/index.html
|
||||
.. _`OpenStack High Availability Guide`: http://docs.openstack.org/ha-guide/index.html
|
||||
.. _`OpenStack Security Guide`: http://docs.openstack.org/sec/
|
||||
.. _`Virtual Machine Image Guide`: http://docs.openstack.org/image-guide/
|
||||
|
||||
.. _`OpenStack End User Guide`: http://docs.openstack.org/user-guide/index.html
|
||||
.. _`OpenStack API Guide`: http://developer.openstack.org/api-guide/quick-start/
|
||||
.. _`Command-Line Interface Reference`: http://docs.openstack.org/cli-reference/
|
||||
|
||||
.. _`Complete API Reference`: http://developer.openstack.org/api-ref.html
|
||||
.. _`API specifications`: http://specs.openstack.org/
|
||||
.. _`Object Storage API v1`: http://docs.openstack.org/developer/swift/#object-storage-v1-rest-api-documentation
|
||||
|
||||
.. _`Infrastructure User Manual`: http://docs.openstack.org/infra/manual/
|
||||
|
|
@ -18,12 +18,11 @@ Contents
|
|||
|
||||
quickstart.rst
|
||||
additional-git-workflow.rst
|
||||
blueprints-and-specs.rst
|
||||
doc-bugs.rst
|
||||
docs-review.rst
|
||||
team-structure.rst
|
||||
docs-structure.rst
|
||||
content-specs.rst
|
||||
blueprints-and-specs.rst
|
||||
api-guides.rst
|
||||
project-install-guide
|
||||
topic-structure.rst
|
||||
|
|
|
|||
Loading…
Reference in New Issue