[doc-contrib-guide] Update release and install/deploy docs

Remove outdated or unneeded information, particularly guide lists.

Change-Id: I53cc71a9645a28e34b78aefea0ec53ae7db6520d
This commit is contained in:
Petr Kovar 2018-02-06 21:03:25 +01:00
parent adcc14cd0b
commit c6a983fdc1
11 changed files with 39 additions and 438 deletions

View File

@ -1,36 +1,32 @@
.. _content-specs:
=====================
Content specification
=====================
=============================
Blueprints and specifications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=============================
The Documentation team uses specifications in the `docs-specs repository
<https://git.openstack.org/cgit/openstack/docs-specs>`_ to maintain large
changes. Approved specifications are published at `Documentation Program
Specifications <https://specs.openstack.org/openstack/docs-specs>`_.
For tracking purposes, a blueprint is created for each specification. It is
also good practice to contact the project team or subteam for the book you want
to change to discuss your changes before starting work.
For tracking purposes, a blueprint is created for each specification.
Use blueprints and specifications:
* For any large reorganization of a deliverable or set of deliverables.
* For infrastructure or automation work that needs to be designed prior to
proposing a patch.
* When adding an entirely new deliverable to the docs project.
* 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.
* For any large reorganization of a deliverable or set of deliverables.
* For automation work that needs to be designed prior to proposing a patch.
* For work that should definitely be discussed at a summit.
* For work that should definitely be discussed at a project teams gathering.
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>`_.
Use bugs against openstack-manuals or openstack-api-site:
Use bugs against a particular repository with documentation:
* For known content issues, even if you have to do multiple patches to close
the bug.
@ -38,305 +34,3 @@ Use bugs against openstack-manuals or openstack-api-site:
* For known errors in a document.
For more information, see :ref:`doc_bugs`.
Release-specific documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Release-specific documentation is published continuously as changes are
made, with different versions for each series.
To patch release-specific documentation, submit your
patch to the master branch with "backport: xxxx" (for example, backport:
kilo) in the commit message. During Pike, much of the material
maintained by the documentation team was moved into project team
repositories, so patching the same content for different release
series may mean looking for the relevant files in multiple places.
.. note::
The following guides were release specific before the Pike
migration:
* Configuration reference
* Command-line reference
* Installation guides
* Networking guide
For these guides, the docs.openstack.org site defaults to the current release,
with the previous two releases being available under the ``More Releases
& Languages`` drop-down. At release time, the documentation release team
will update the default page to the new release, and remove the link to
the oldest release. These docs are still available online for people who
have direct URLs to the content, but they are no longer linked from the
main site. For books written in DocBook XML, these old versions are clearly
marked with the release name in red down the left-hand margin. We are
currently developing a similar method of marking older books written in RST.
The core team tracks usage of older versions, and as usage falls, can
remove them entirely.
Installation Guides
-------------------
Starting with Pike, the OpenStack Installation Guides
are maintained by the project teams, with assistance from the
documentation team. The guides describe a manual install process for
multiple distributions based on openSUSE and SUSE Linux Enterprise
Server; Red Hat Enterprise Linux and CentOS; and Ubuntu 16.04 (LTS).
Prior to Pike, the documentation team maintained OpenStack
Installation Guides:
.. list-table::
:header-rows: 1
* - Document
- Source location
- Target location
* - Installation Guide for openSUSE and SUSE Linux Enterprise Server
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide
- https://docs.openstack.org/ocata/install-guide-obs/
* - Installation Guide for Red Hat Enterprise Linux and CentOS
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide
- https://docs.openstack.org/ocata/install-guide-rdo/
* - Installation Guide for Ubuntu 16.04 (LTS)
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide
- https://docs.openstack.org/ocata/install-guide-ubuntu/
* - Installation Guide For Debian With Debconf (is not provided for Ocata)
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide
- https://docs.openstack.org/newton/install-guide-debconf/
* - Installation Guide For Debian (is not provided for Ocata)
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide
- https://docs.openstack.org/newton/install-guide-debian/
Guides for deployers and administrators
---------------------------------------
As of Pike, the configuration reference and administration guide(s)
are maintained by each project team.
Prior to Pike, the documentation team maintained the following
combined guides:
* `OpenStack Configuration Reference
<https://docs.openstack.org/ocata/config-reference/>`_:
Contains a reference listing of all configuration options for OpenStack
services by release version.
* `OpenStack Networking Guide
<https://docs.openstack.org/ocata/networking-guide/>`_:
This guide targets OpenStack administrators seeking to deploy and manage
OpenStack Networking (neutron).
.. list-table::
:header-rows: 1
* - Document
- Source location
- Target location
* - Configuration Reference
- Maintained in project specific repositories
- https://docs.openstack.org/ocata/config-reference/
* - OpenStack Networking Guide
- https://github.com/openstack/neutron/tree/master/doc/source/admin
- https://docs.openstack.org/ocata/networking-guide/
Continuously released documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These guides cover multiple versions and follows 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:
* HA Guide: Updated last at Havana timeframe, still needs updates
Guides for deployers and administrators
---------------------------------------
.. list-table::
:header-rows: 1
* - Document
- Source location
- Target location
* - OpenStack Architecture Design Guide
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/arch-design
- https://docs.openstack.org/arch-design/
* - OpenStack Administrator Guide
- Maintained in project specific repositories
- https://docs.openstack.org/admin-guide/
* - OpenStack High Availability Guide
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/ha-guide
- https://docs.openstack.org/ha-guide/
* - OpenStack Security Guide
- https://git.openstack.org/cgit/openstack/security-doc/tree/security-guide
- https://docs.openstack.org/security-guide/
* - OpenStack Virtual Machine Image Guide
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/image-guide
- https://docs.openstack.org/image-guide/
Guides for end users
--------------------
* `OpenStack API Guide
<https://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
<https://docs.openstack.org/cli-reference/>`_:
Automatically generates help text for CLI commands and subcommands.
* `OpenStack End User Guide
<https://docs.openstack.org/user/>`_:
This guide contains project-specific documentation for using OpenStack
services and libraries.
.. list-table::
:header-rows: 1
* - Document
- Source location
- Target location
* - OpenStack API Guide
- https://git.openstack.org/cgit/openstack/api-site/tree/api-quick-start
- https://developer.openstack.org/api-guide/quick-start/
* - OpenStack Command-Line Interface Reference
- https://git.openstack.org/cgit/openstack/oslo.config/tree/doc/source/cli
- https://docs.openstack.org/cli-reference/
* - OpenStack Project User Guides
- Maintained in project specific repositories
- https://docs.openstack.org/user/
API documentation
-----------------
* `Complete API Reference <https://developer.openstack.org/api-guide/quick-start/index.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
<https://docs.openstack.org/swift/latest/api/object_api_v1_overview.html>`_
Project-specific guides
-----------------------
Each project maintains its own guides for installation,
administration, configuration reference, and contributors. They are
published from each project repository. See the
`OpenStack Projects <https://docs.openstack.org/openstack-projects.html>`_ and
the `OpenStack API Bindings <https://docs.openstack.org/language-bindings.html>`_
pages for more information.
Each project's repo has a ``doc/source`` directory where RST source
files are stored. They are built automatically with Sphinx when the
patch is merged. For example, see
the ` horizon documentation source <https://git.openstack.org/cgit/openstack/horizon/tree/doc/source>`_
and the `built documentation <https://docs.openstack.org/horizon/>`_.
* `Infrastructure User Manual <https://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.
.. list-table::
:header-rows: 1
* - Document
- Source location
- Target location
* - Documentation Contributor Guide
- https://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/doc-contrib-guide
- https://docs.openstack.org/doc-contrib-guide/
* - Python Developer Documentation
- https://git.openstack.org/cgit/openstack/<project>/tree/master/doc/source/,
such as https://git.openstack.org/cgit/openstack/nova/tree/doc/source
- https://docs.openstack.org/openstack-projects.html
* - Language Bindings and Python Clients
- https://git.openstack.org/cgit/openstack/python-<project>client/tree/master/doc/source/,
such as https://git.openstack.org/cgit/openstack/python-novaclient/tree/doc/source
- https://docs.openstack.org/language-bindings.html
* - OpenStack Project Infrastructure
- https://git.openstack.org/cgit/openstack-infra/system-config/tree/doc/source
- https://docs.openstack.org/infra/system-config/
* - Tempest Testing Project
- https://git.openstack.org/cgit/openstack/tempest/tree/doc/source
- https://docs.openstack.org/tempest/latest/
Guides for contributors
-----------------------
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/<projectname>/latest): 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/<projectname>/latest): 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

View File

@ -4,11 +4,12 @@ Landing pages on docs.openstack.org
The main index pages on docs.openstack.org are part of the
``openstack-manuals`` repository in the ``www`` folder. These are
generated with using a :ref:`template generator <template-generator>`.
generated with using a template generator as described in
:doc:`doc-tools/template-generator`.
Official OpenStack projects hosted on the ``docs.openstack.org`` site
should add their links to the main index pages as explained at
:ref:`template-generator`.
:doc:`doc-tools/template-generator`.
For projects with many subprojects, like deployment projects or
plug-in lists of networking or bare metal, the main project page

View File

@ -12,7 +12,7 @@ Reviewing documentation
OpenStack documentation is treated in the same way as code, and follows the
standard code review process. To see what documentation changes are ready for
review, use the `Documentation Program Dashboard
<https://is.gd/openstackdocsreviewreloaded>`_ or the appropriate list of
<https://is.gd/openstackdocsdashboard>`_ or the appropriate list of
Gerrit reviews for repositories with documentation.
The Documentation Program Dashboard only lists changes to repositories that
@ -46,7 +46,7 @@ Once done, follow the steps below to submit a patch review.
#. If you want to review patches for the repositories managed by the
Documentation project or the project's subteams, go to the
`Documentation Program Dashboard
<https://is.gd/openstackdocsreviewreloaded>`_.
<https://is.gd/openstackdocsdashboard>`_.
To review patches for project teams' repositories, use the list of Gerrit
changes for the appropriate project.

View File

@ -1,14 +0,0 @@
=============
Landing pages
=============
There are now central landing pages for the various project guides.
For example, there is now one central place for the Administrator Guide
at `https://docs.openstack.org/pike/admin/index.html`.
To add your project content to these guides, change the file
`www/project-data/latest.yaml
<http://git.openstack.org/cgit/openstack/openstack-manuals/tree/www/project-data/latest.yaml>`_
in the openstack-manuals repository.
See :ref:`template-generator` for details.

View File

@ -72,12 +72,6 @@ Setting up
#. Commit the changes to your project repository for review.
To create or update the master index file, create or update the
``www/project-deploy-guide/RELEASE/index.html`` file at the
``openstack-manuals`` repository.
For draft (unreleased) version, replace ``RELEASE`` with ``draft``.
After these changes merge, you can set up the jobs for building in the
OpenStack Infra ``project-config`` repository:
@ -118,6 +112,9 @@ OpenStack Infra ``project-config`` repository:
#. Commit the changes to the infra repository for review.
To update the main index pages with a link to your deployment guide, see
:doc:`doc-tools/template-generator`.
Deployment guide and installation guide links
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

View File

@ -86,4 +86,3 @@ by the documentation team.
project-install-guide.rst
project-deploy-guide.rst
landing-pages.rst

View File

@ -8,34 +8,25 @@ Pike and later
~~~~~~~~~~~~~~
Each official OpenStack project should maintain an installation guide
following the layout described in the `documentation migration
spec`_. When the guide is available, update
``openstack-manuals/www/project-data/latest.yaml`` to include
following the layout described in :doc:`project-guides`. When the guide is
available, update ``openstack-manuals/www/project-data/latest.yaml`` to include
information about the project and ensure that the
``has_install_guide`` flag is set to ``true`` to ensure that the guide
is listed along with the guides from other projects.
.. _documentation migration spec: http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html
Newton and Ocata
~~~~~~~~~~~~~~~~
For the Newton release, a new method of publishing installation
guides is being implemented. This will allow each big tent project to
create their own installation guide, based on a standard template,
in their own repository. These guides are then centrally published to
For the Newton and Ocata releases only, big tent projects created their own
installation guides, based on a standard template, in their own repository.
These guides were then centrally published to
`docs.openstack.org <https://docs.openstack.org>`_.
.. warning::
These instructions are superseded by the `documentation migration
spec`_. New installation guides should be created using the layout
defined in the spec, rather than the following instructions.
For updates on the progress of this project, see the `Install Guide wiki
page <https://wiki.openstack.org/wiki/Documentation/InstallGuideWorkItems>`_.
If you would like to help out, `attend a meeting
<http://eavesdrop.openstack.org/#Documentation_Install_Team_Meeting>`_.
The following instructions are superseded by :doc:`project-guides`. New
installation guides should be created using the layout defined in the spec,
rather than the following instructions.
Set up project specific installation guides:
@ -147,8 +138,3 @@ After these changes have merged, you can set up the jobs for building.
This schedules the Install Guide jobs.
#. Commit the changes to the infra repository for review.
To create or update the master index file, create or update the
``www/RELEASE/install/index.html`` file and the
``doc/install-guide/source/additional-services.rst`` at the
``openstack-manuals`` repository.

View File

@ -57,12 +57,12 @@ OpenStack Manuals no longer handles release notes for the project teams.
However, we do need to write release notes for our documentation. Release
notes should be added as major changes occur throughout the release, however
this is often overlooked - both by authors and reviewers - and thus a final
review is needed to check that all major changes are in. Contact each
Specialty Team lead, listed at :doc:`../team-structure`, and ask them for
the notes for the books they look after. The source repository for release
notes is `openstack-manuals/releasenotes/source/RELEASENAME` and they are
review is needed to check that all major changes are in. Contact each subteam
lead, listed at :doc:`../team-structure`, and ask them for the notes for the
documentation they look after. The source for release notes is
``openstack-manuals/releasenotes/source/RELEASENAME.rst`` and they are
published to
`https://docs.openstack.org/releasenotes/openstack-manuals/RELEASENAME.html`.
``https://docs.openstack.org/releasenotes/openstack-manuals/RELEASENAME.html``.
.. _release-www-page-updates:
@ -161,7 +161,7 @@ Make the following changes in the **openstack-manuals** repository:
pushed at release time, so be prepared to have the release day
patches ready well ahead of the official release time. You can
check the current gate status at `Zuul status
<http://status.openstack.org/zuul/>`_ to get an idea of the current
<http://zuul.openstack.org/>`_ to get an idea of the current
merge times.
Generate the site map
@ -203,23 +203,7 @@ To:
This guide documents OpenStack Newton and Mitaka releases.
However, we will keep the documentation on the
`docs.openstack.org <https://docs.openstack.org/>`_
page for a while so that the users can refer the guides if necessary.
.. seealso::
See :ref:`docs_builds_eol` for instructions for building
documentation for versions past their end-of-life.
Removing series landing pages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To remove the landing pages for a series that has passed its end of
life date, delete the series directory under ``www`` and remove the
associated project data file.
.. code-block:: console
$ git rm -r www/SERIES
$ git rm www/project-data/SERIES.yaml

View File

@ -10,24 +10,17 @@ Release day is usually 1300UTC on the `initial release date` listed on the
*Four to six weeks before release*
Ping packagers to locate pre-release packages to test the Installation
Guide against, and start looking for willing volunteers to help test.
*Four weeks*
Ping Cross Project Liaisons (CPLs) to check their chapters, and ping
packagers to check on package availability. As soon as pre-release
packages are available, ask people to start testing.
Guides against, and start looking for willing volunteers to help test.
*Two to four weeks*
Ping Speciality Team leads to review and update release notes for
openstack-manuals.
Ping subteam leads to review and update release notes for openstack-manuals.
*At RC1*
When projects create their branches and land the first patch,
they will automatically have branch-specific documentation. After
the branches are created, create the project data file in the
``openstack-manuals`` repository for the new series.
When projects create their branches and land the first patch, they will
automatically have branch-specific documentation.
*Before or on release day*
Update the series settings in the template generator and add the
Create a project data file in the ``openstack-manuals`` repository for the
new series. Update the series settings in the template generator and add the
landing page for the next series by copying the templates from the
current release to the new release directory.

View File

@ -5,11 +5,8 @@ Topic structure
===============
The OpenStack community welcomes all contributors to documentation. This
section provides recommendations on how to structure the content that you
submit to the ``openstack-manuals`` repository.
Organize technical information in topics. Use the principles of topic-based
authoring in all technical publications.
section provides ideas on how to structure the content for an OpenStack
project by using the principles of topic-based authoring.
Topic-based authoring is a method of content creation in which information
is structured in small chunks of a particular type. In contrast to

View File

@ -29,11 +29,6 @@ Contributor Guide
* Updated guide to be relevant for updated openstack-manuals.
* General bug fixes and updates.
API Guides
~~~~~~~~~~
* TBD
Security Guide
~~~~~~~~~~~~~~
@ -41,40 +36,9 @@ Security Guide
* Rework of 'node hardening' section
* Various fixes such as grammar and incorrect hyperlinks
Training Guides
~~~~~~~~~~~~~~~
* TBD
Training Labs
~~~~~~~~~~~~~
* Support for the new OpenStack release will be available shortly
after the release of Pike.
* Various bug fixes and minor improvements in the host scripts.
Translations
~~~~~~~~~~~~
Besides updating the existing translated manuals,
the Internationalization (i18n) team added the following new manuals:
* German:
* TBD
* Indonesian:
* TBD.
* Japanese:
* TBD
* Korean:
* TBD
* Simplified Chinese:
* TBD