openstack/docs-specs
Code Issues Proposed changes

Retire docs-specs

Browse Source 
We haven't used this in a long time and with the transition of docs from
a project to a SIG, it's not likely to be used again going forward.

Leave the .zuul.yaml file with noop-jobs to allow this patch to merge.

Change-Id: I557bace8008cc3b4fc1f78264f93291c49f897ad
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Depends-On: Ie3ed990df99057896130ed0f7d5cf6c07db8c962
This commit is contained in:
Stephen Finucane 2019-05-04 11:18:39 -06:00
parent 81abe0dfe2
commit 5a82d7e9a2
83 changed files with 7 additions and 10330 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
.gitignore vendored
View File

@ -1,18 +0,0 @@
.DS_Store
AUTHORS
ChangeLog
build
.tox
.venv
*.egg*
*.swp
*.swo
*.pyc
.testrepository
# Editors
*~
.*.swp
.bak
/.project

9
.zuul.yaml
View File

@ -1,9 +0,0 @@
- project:
templates:
- openstack-specs-jobs
check:
jobs:
- openstack-tox-py27
gate:
jobs:
- openstack-tox-py27

3
LICENSE
View File

@ -1,3 +0,0 @@
This work is licensed under a Creative Commons Attribution 3.0 Unported License.
http://creativecommons.org/licenses/by/3.0/legalcode

67
README.rst
View File

@ -1,62 +1,9 @@
========================
Team and repository tags
========================
This project is no longer maintained.
.. image:: https://governance.openstack.org/tc/badges/docs-specs.svg
:target: https://governance.openstack.org/tc/reference/tags/index.html
The contents of this repository are still available in the Git
source code management system. To see the contents of this
repository before it reached its end of life, please check out the
previous commit with "git checkout HEAD^1".
.. Change things from this point on
======================================
OpenStack Documentation Specifications
======================================
This git repository is used to hold approved design specifications for
additions to the OpenStack Documentation program. Reviews of the specs
are done in gerrit, using a similar workflow to how we review and
merge changes to the docs and supporting tools.
The layout of this repository is::
specs/<release>/
You can find an example spec in `doc/source/specs/template.rst`.
Fill it in with the details of a new blueprint for documentation.
For docs, blueprints are required for larger, coordinated projects but
not for small fixes. It's a judgement call for whether you need a
spec, so feel free to ask in the
#openstack-doc IRC channel or on the openstack-docs mailing list.
To propose a specification for a release-specific doc like the install guides
or the configuration reference, add a new file to the
`specs/<release>` directory and post it for review. The implementation
status of a blueprint for a given release can be found by looking at the
blueprint in Launchpad (and the spec links to Launchpad).
Please realize that not all approved blueprints will get fully implemented.
Prior to the Juno development cycle, this repository was not used for spec
reviews. Reviews prior to Juno were completed entirely through `Launchpad
blueprints <http://blueprints.launchpad.net/openstack-manuals>`_.
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
https://docs.openstack.org/infra/manual/developers.html#development-workflow.
To validate that the specification is syntactically correct (i.e. get more
confidence in the Zuul result), please execute the following command::
$ tox
After running ``tox``, the documentation will be available for viewing in HTML
format in the ``doc/build/`` directory. Please do not check in the generated
HTML files as a part of your commit.
The files are published at https://specs.openstack.org/openstack/docs-specs.
The git repository is located at
https://git.openstack.org/cgit/openstack/docs-specs/.
For any further questions, please email
openstack-discuss@lists.openstack.org.

277
doc/source/conf.py
View File

@ -1,277 +0,0 @@
# -*- coding: utf-8 -*-
#
# Tempest documentation build configuration file, created by
# sphinx-quickstart on Tue May 21 17:43:32 2013.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import datetime
import subprocess
import sys
import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['openstackdocstheme',
'yasfb',
]
# Allow badges in README
suppress_warnings = ['image.nonlocal_uri']
# Feed configuration for yasfb
feed_base_url = 'http://specs.openstack.org/openstack/docs-specs'
feed_author = 'OpenStack Documentation Team'
todo_include_todos = True
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Docs Specs'
copyright = u'%s, OpenStack Documentation Team' % datetime.date.today().year
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = [
'_build',
'**/template.rst',
'**/skeleton.rst',
]
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
add_module_names = False
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
modindex_common_prefix = ['docs-specs.']
# Do not warn about non-local image URI
suppress_warnings = ['image.nonlocal_uri']
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'openstackdocs'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = '%Y-%m-%d %H:%M'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
html_domain_indices = False
# If false, no index is generated.
html_use_index = False
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'Docs-Specsdoc'
# -- Options for LaTeX output --------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'Docs-specs.tex', u'Docs Specs',
u'OpenStack Documentation Team', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for Texinfo output ------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'Docs-specs', u'Documentation Design Specs',
u'OpenStack Documentation Team', 'docs-specs', 'Design specifications for the Documentation program.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# -- Options for Epub output ---------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = u'Docs Specs'
epub_author = u'OpenStack Documentation Team'
epub_publisher = u'OpenStack Documentation Team'
epub_copyright = u'2014, OpenStack Documentation Team'
# The language of the text. It defaults to the language option
# or en if the language is not set.
#epub_language = ''
# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#epub_identifier = ''
# A unique identification for the text.
#epub_uid = ''
# A tuple containing the cover image and cover page html template filenames.
#epub_cover = ()
# HTML files that should be inserted before the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_pre_files = []
# HTML files shat should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []
# A list of files that should not be packed into the epub file.
#epub_exclude_files = []
# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3
# Allow duplicate toc entries.
#epub_tocdup = True

100
doc/source/index.rst
View File

@ -1,100 +0,0 @@
.. docs-specs documentation master file
====================================
Documentation Program Specifications
====================================
Rocky approved specs
====================
.. toctree::
:glob:
:maxdepth: 1
specs/rocky/*
Queens approved specs
=====================
.. toctree::
:glob:
:maxdepth: 1
specs/queens/*
Pike approved specs
======================
.. toctree::
:glob:
:maxdepth: 1
specs/pike/*
Ocata approved specs
======================
.. toctree::
:glob:
:maxdepth: 1
specs/ocata/*
Newton approved specs
======================
.. toctree::
:glob:
:maxdepth: 1
specs/newton/*
Mitaka approved specs
======================
.. toctree::
:glob:
:maxdepth: 1
specs/mitaka/*
Liberty approved specs
======================
.. toctree::
:glob:
:maxdepth: 1
specs/liberty/*
Kilo approved specs
===================
.. toctree::
:glob:
:maxdepth: 1
specs/kilo/*
Juno approved specs
===================
.. toctree::
:glob:
:maxdepth: 1
specs/juno/*
Writing specifications
======================
.. toctree::
:maxdepth: 1
README <readme>
==================
Indices and tables
==================
* :ref:`search`

1
doc/source/readme.rst
View File

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

1
doc/source/specs
View File

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

13
requirements.txt
View File

@ -1,13 +0,0 @@
# The order of packages is significant, because pip processes them in the order
# of appearance. Changing the order has an impact on the overall integration
# process, which may cause wedges in the gate later.
doc8 # Apache-2.0
sphinx>=1.6.2 # BSD
openstackdocstheme>=1.11.0 # Apache-2.0
testrepository>=0.0.18 # Apache-2.0/BSD
testtools>=1.4.0 # MIT
# Note the following is not in global-requirements but this repo is
# not used in repositories in general.
yasfb>=0.6.1

28
setup.cfg
View File

@ -1,28 +0,0 @@
[metadata]
name = docs-specs
summary = OpenStack Documentation Program Specs
description-file =
README.rst
author = OpenStack
author-email = openstack-discuss@lists.openstack.org
home-page = http://specs.openstack.org/openstack/docs-specs/
classifier =
Intended Audience :: Writers
License :: OSI Approved :: Apache Software License
Operating System :: POSIX :: Linux
Programming Language :: Python
Programming Language :: Python :: 2
Programming Language :: Python :: 2.7
Programming Language :: Python :: 3
Programming Language :: Python :: 3.3
Programming Language :: Python :: 3.5
[build_sphinx]
builders = html
all_files = 1
build-dir = doc/build
source-dir = doc/source
warning-is-error = 1
[wheel]
universal = 1

29
setup.py
View File

@ -1,29 +0,0 @@
# Copyright (c) 2013 Hewlett-Packard Development Company, L.P.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# THIS FILE IS MANAGED BY THE GLOBAL REQUIREMENTS REPO - DO NOT EDIT
import setuptools
# In python < 2.7.4, a lazy loading of package `pbr` will break
# setuptools if some other modules registered functions in `atexit`.
# solution from: http://bugs.python.org/issue15881#msg170215
try:
import multiprocessing # noqa
except ImportError:
pass
setuptools.setup(
setup_requires=['pbr>=2.0'],
pbr=True)

93
specs/juno/common-glossary-setup.rst
View File

@ -1,93 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Better share glossary across repositories
==========================================
https://blueprints.launchpad.net/openstack-manuals/+spec/common-glossary-setup
Problem description
===================
The repositories security-doc, operations-guide, and openstack-manuals
share the glossary. In the future the training-guides repository might
use it as well. We should only maintain it in one place.
Also, translation should be only done in one place. Right now,
translations happen in any of these repositories: In openstack-manuals
using a separate POT file, in security-doc and operations-guide as
part of the books.
Currently, the glossary is manually imported in the operations-guide
and security-doc repositories when necessary. The operations-guide
even contains a slightly different header than the version in the
openstack-manuals repository.
The glossary terms must be available to maven at build time to ensure
the links all work correctly.
Proposed change
===============
We should continue to have a master source glossary.
The openstack-manuals repository should continue to be the master
source.
Once a change to the glossary in the master source happens, it will be
proposed to the other repositories via a Jenkins job.
Alternatives
------------
* Using a separate glossary repository and using git submodules in the
other repositories. Our current gerrit setup does not allow git
submodules, so this is not feasible with the current infrastructure.
* Another option would be to checkout the repository containing the
glossary and its translation at a well-known location at build
time. This option requires that every contributor needs to have the
glossary locally when building locally, which is likely too much to
ask of contributors.
* Another alternative may be to create a new openstack/glossary
repository and always copy from there, rather than having
openstack/openstack-manuals/doc/glossary be the storing place.
Raising the level to a repo may help get more contributions to the
glossary.
Implementation
==============
Assignee(s)
-----------
Andreas Jaeger (jaegerandi)
Work Items
----------
* Move files as needed.
* Test solution manually for Security Guide and Operations Guide.
* Change build jobs as needed.
Dependencies
============
Testing
=======
References
==========
Current build of complete glossary:
http://docs.openstack.org/glossary/content/glossary.html

133
specs/juno/create-networking-guide.rst
View File

@ -1,133 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
================
Networking Guide
================
https://blueprints.launchpad.net/openstack-manuals/+spec/create-networking-guide
Problem description
===================
Since the Havana release, OpenStack has not had a single guide devoted to
understanding and deploying OpenStack Networking. There is some information
in other guides, particularly the Cloud Administrators Guide, but no single
guide that discusses different networking scenarios and solutions.
Proposed change
===============
We should create a Networking Guide, following roughly the outline here:
https://wiki.openstack.org/wiki/NetworkingGuide/TOC
Additionally, a Troubleshooting chapter may be included, subject to
time constraints.
The target audience for this information is cloud administrators who
have experience with OpenStack administration and general system
administration, but who may not be especially knowledgeable about
networking concepts.
This document is targeted for the Juno release. It is explicitly
documenting current best practices for OpenStack Networking (neutron).
It will not document any plug-ins or setups that are deprecated in Juno.
Though the instructions in the guide are for neutron, the introduction
should contain a brief discussion on the different options available,
including nova-network, what this guide focuses on, and why one would
choose those options.
The base architecture uses three nodes: a controller and compute nodes
as set up in the Install Guide, plus a network node to run Neutron
agents. This is the same architecture used in the Cloud Administrators
Guide:
http://docs.openstack.org/admin-guide-cloud/networking_arch.html
It will use the same conventions for naming and services as the Install
Guide, many of which are covered on the wiki:
https://wiki.openstack.org/wiki/Documentation/Guide_conventions
Network types to be covered:
* Local
* VLAN
* GRE
* VXLAN
Mechanisms to be covered:
* Linux Bridge
* OVS
* Open Daylight
* L2 Population
* Proprietary (depending on time constraints)
All instructions will use the ML2 plug-in for mechanism drivers.
Deprecated plug-ins (for example, for OVS or Linux Bridge) will
not be discussed.
Timeline and Events:
* docs swarm (2014-08-09)
* ops meetup (upcoming)
* bug squash day (upcoming)
Alternatives
------------
* Adding more information on networking to guides such as the Cloud
Administrators Guide, Operators Guide, and Install Guide. These
documents already contain some networking information. However,
for them to cover the full breadth of what's proposed could add
significant bulk to each.
Implementation
==============
The Networking Guide will live alongside other guides in the
openstack-manuals repository. There is already some stub content.
Assignee(s)
-----------
Primary assignee:
shaunm-gnome
Other contributors:
nickchase
phil-hopkins-a
ionosphere80
emagana
loquacity
Work Items
----------
* Stub out outline of sections and information to be included.
* Determine whether content already exists, and whether it can be included
or whether it needs to be copied in and edited.
* Have multiple contributors write sections with help from SMEs.
* Review contributions, prioritize content, and possibly prune for release.
Dependencies
============
Need reviewers from Neutron
Testing
=======
* Have SMEs review all conceptual information for accuracy.
* Manually test all instructions to ensure they work.
References
==========
None

125
specs/juno/heat-templates.rst
View File

@ -1,125 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
======================================
Add documentation about heat templates
======================================
https://blueprints.launchpad.net/openstack-manuals/+spec/heat-templates
Problem description
===================
The documentation about how to write heat templates in the openstack-manuals
repository is almost nonexistent. The developer resources are a good starting
point, but don't provide enough information to easily learn how to write
meaningful templates.
The HOT reference (properties and attributes of resources, available functions,
...) is published only for the current development branch, from the heat
documentation (in the developer/ section of the published documentation). This
reference should be available for users along the other references (config
reference, CLI reference), for each released version of heat.
Proposed change
===============
Two changes are proposed:
* Adding a chapter to the user guide
* Providing a new guide: "Heat Orchestration Templates (HOT) Reference Guide"
Adding a chapter to the user guide
----------------------------------
A first section would cover the basic aspects of templates:
* Architecture, format and languages
* Resources definition
* Parameters definition
* Usage of functions and attributes
* Links between resources
This section would cover the base resources: nova server, neutron nets, subnets
and ports, cinder volumes
A second section will document how to use more complex resources such as:
* WaitConditions
* HA and alarming
* AutoScaling
Providing a new guide: the HOT reference
----------------------------------------
This guide will be automatically built from the heat source code and
documentation.
Alternatives
------------
Some alternatives we considered and discuss on the mailing list previously
include:
* Starting a new standalone guide for Templates within openstack-manuals,
sourced in DocBook. We decided the overhead for a new non-automated guide was
too much, and end users are going to want to know this exists.
* Convert the entire End User Guide from DocBook to RST and build with Sphinx,
using the oslosphinx tempate for output. We would lose the translation
toolchain and the PDF from this output chain is not as nice as the DocBook
PDF.
So, to take the best of both tool chains, this proposal chooses to create a
chapter in the End User Guide, ultimately in DocBook, but through an RST path.
Implementation
==============
The documentation will initially be written in RST, to ease developers
contributions. A tool to convert RST to DocBook will be provided.
The template reference provided in the heat repository will be converted to
DocBook and imported in an dedicated guide.
Assignee(s)
-----------
Gauvain Pocentek (gpocentek)
Work Items
----------
* Write the RST to DocBook conversion tool.
* Write the doc in RST.
* Import the result of the conversion in the user guide when ready.
* (Maybe) Automate the import for future updates.
* Automatically publish the reference information for heat templates in a
separate guide.
Dependencies
============
Testing
=======
Minimalistic but functional templates will be provided along the guide. Default
values for parameters will be set to easily work on a devstack environment.
This should ease the testing.
These templates could be provided as part of the `heat-templates repository`_.
.. _`heat-templates repository`: https://git.openstack.org/cgit/openstack/heat-templates
References
==========
* https://git.openstack.org/cgit/openstack/heat/tree/doc/source/template_guide
* https://git.openstack.org/cgit/openstack/heat-templates
* http://docs.openstack.org/developer/heat/template_guide/openstack.html

99
specs/kilo/draft-publishing.rst
View File

@ -1,99 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===========================
Publishing of draft manuals
===========================
https://blueprints.launchpad.net/openstack-manuals/+spec/draft-publishing
Problem description
===================
Currently, the following guides are not published at all from the
master branch of the git repository:
* Networking Guide
* Install Guide
* RST User Guides (will change while we discuss this spec)
This makes it difficult for contributors to review current status.
We publish the Configuration reference to
http://docs.openstack.org/trunk/ .
We also have a trunk index page that speaks about "Draft" guides but
references also continuous publishing guides which might confuse users.
Another challenge is drafts of translated guides. Currently we do not
differentiate between fully translated guides and drafts, the only
difference is a link in the index page.
Proposed change
===============
#. Publish draft content to a special location like `/draft/`.
#. Create a single page that references all draft documents and only
those, this page should be hidden. The page is `/draft/draft-index.html`
#. Remove the current `/trunk/index.html` page and links to it.
#. Take care that search machines do not index these pages.
#. Ensure that any partial translated pages do not publish to `/lang/trunk/`
but instead to `/lang/draft`.
For translated content:
#. Publish draft translated content to `/draft/LANG/`.
#. Add the guides to `/draft/draft-index.html` index page.
#. Once guides are reviewed and fully translated , move the content to
`/LANG/` and reference it from a public language specific index page.
Alternatives
------------
#. Keep status quo
#. Publish to another location like `/trunk/`.
Implementation
==============
* Change location of publishing.
* Remove `/trunk/index.html` and links to it.
* Add `/draft/` to :file:`robots.txt`.
* Create new `/draft/draft-index.html` page.
* Review translated documents and publish draft translated documents
to `/draft/LANG/` and add links to `/draft/draft-index.html`.
* Remove old pages.
* Regenerate sitemap.
Assignee(s)
-----------
jaegerandi
Work Items
----------
See implementation.
Dependencies
============
None.
Testing
=======
* Test by going to /trunk and making sure redirect is in place.
* Search for draft content to make sure it's not found.
References
==========
* http://lists.openstack.org/pipermail/openstack-docs/2015-April/006243.html
* https://docs.google.com/spreadsheets/d/10HD6iW1CtfB1qT2wVODYiHdC0ysr4xw392VCqHB-aaY/edit?usp=sharing

151
specs/kilo/installguide-kilo.rst
View File

@ -1,151 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=====================================
Installation Guide - Changes for Kilo
=====================================
https://blueprints.launchpad.net/openstack-manuals/+spec/installguide-kilo
Implement mandatory changes and optional enhancements to the Installation
Guide for Kilo.
Problem description
===================
The installation guide requires certain changes to make it work for the
Kilo release of OpenStack.
Proposed change
===============
* Implement mandatory changes and potentially one or more optional
enhancements.
Alternatives
------------
None.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Matt Kassawara (ionosphere80)
Other contributors:
Anyone with installation experience
Work Items
----------
* Mandatory changes
* Overall
- As necessary, make changes to successfully install OpenStack on
Ubuntu 14.04, RHEL 7, CentOS 7, Fedora 21, SLES 12, and openSUSE
13.2 using native methods.
- For RabbitMQ, create and use "openstack" account instead of the
guest account.
- As necessary, note that stock configuration files might require
adding configuration stanzas/options rather than editing them.
- As necessary, change any defaults in stock configuration files
that generate deprecation warnings.
- As necessary, replace "tenant" with "project" to align with
Identity v3 API terminology.
- As necessary, replace "message broker" with "message queue" to
improve wording.
* Identity
- Enable version 3 API.
- Replace deprecated eventlet (default web server) with Apache using
`configuration`_ in upstream keystone repository.
.. _`configuration`: https://git.openstack.org/cgit/openstack/keystone/tree/httpd
- Replace SQL token storage driver with Memcached to improve
performance.
- Replace deprecated python-keystoneclient commands with
python-openstackclient commands.
* Image Service
- Enable version 2 API.
* Block Storage
- Replace deprecated v1 API with v2 API.
* Optional changes
* Overall
- Where available, use the /etc/mysql/conf.d directory for additional
database configuration.
- Install upstream RabbitMQ package if distribution includes an old
version.
- Replace python-serviceclient commands with generic
python-openstackclient commands.
* Networking
- Standardize location for Open vSwitch agent configuration.
- Add content for Linux Bridge agent.
* Object Storage
- Add content for standalone (keystone + swift) deployment.
Note: To simplify patches and shrink the review cycle, patches can
address one distribution rather than all distributions. Use separate
patches to address the same content for additional distributions.
Reviewers should take this into account so that one distribution
can complete patches, tests, and publication independent of other
distributions.
Dependencies
============
* Kilo milestone or RC packages for each distribution supported by the
installation guide.
Testing
=======
* All distributions supported by the installation guide must complete
`testing`_ of at least core services (Identity, Image Service, Compute,
and Networking) and successfully launch an instance using both legacy
networking (nova-network) and Networking (neutron). Distributions that
do not meet these criteria risk temporary removal from publication.
.. _`testing`: https://wiki.openstack.org/wiki/KiloDocTesting
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [install-guide]
in the subject, weekly installation guide `specialty team meeting`_,
weekly `documentation team meeting`_, and potentially etherpads.
.. _`specialty team meeting`: https://wiki.openstack.org/wiki/Documentation/InstallGuide
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

237
specs/kilo/migrate-to-new-web-design.rst
View File

@ -1,237 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===========================
Migration to New Web Design
===========================
https://blueprints.launchpad.net/openstack-manuals/+spec/redesign-docs-site
The documentation team has reviewed and vetted a new web design. Here are the
example pages:
* `Main page <http://openstack-homepage.bitballoon.com/docs>`_
* `Content view <http://openstack-homepage.bitballoon.com/docs/book>`_
* `Search results <http://openstack-homepage.bitballoon.com/docs/search>`_
* `Example language landing page <http://openstack-homepage.bitballoon.com/docs/ja>`_
This blueprint describes the steps required to implement this new web design.
Problem description
===================
In brief, we have design problems that are addressed with the new design. The
problem to solve is how to get many documents to use the new design.
A related relevant document is the
`Docs.OpenStack.org Redesign Project Brief
<https://docs.google.com/document/d/1GGKTKHDMc8A0jerdv-K3ql0udnxMr-j4DlhL2Cj6kcw/edit?usp=sharing>`_ which describes the many problems with the current design.
The problem to solve with this blueprint specifically is getting the design
into Sphinx/jinja templates for use with RST source, as well as getting RST
source files from certain DocBook source files.
This is a phased approach to try to get many but not all docs migrated in the
Kilo release time frame.
Proposed change
===============
In the Kilo time frame, migrate these books to the new design:
* End User Guide
* Admin User Guide
As time permits, continue to migrate these books to the new design:
* Cloud Administrator Guide
* High Availability Guide
* API Quick Start Guide
* Virtual Machine Image Guide
To limit the scope of the migration, these books will not be migrated:
* Install Guides
* Operations Guide
* Security Guide
* Architecture Design Guide
These deliverables will remain in DocBook and use the Maven plugin for builds
for the Kilo release.
Alternatives
------------
Rather than use RST/Sphinx for the new design, we could migrate to
markdown/Jekyll which is what the prototype design is already using. The
OpenStack ecosystem currently supports Python systems like Sphinx and
oslosphinx is available with a theme already.
We could get rid of DocBook completely for all books rather than the phased
approach. I don't think that we have the time to do that in a six-month
release, so I'm proposing a phased approach.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
annegentle
Other contributors:
jagerandi
loquacities
klevenstein
dhellman
Work Items
----------
Research:
January 2015
- Investigate how to publish PDF files within this new design.
- Investigate using index.rst collections across repos for new deliverable
assembly. This is not a required task for the migration, but will certainly
help with information architecture going forward towards "every page is page
one" rather than book-like deliverables. (jaegerandi)
Frameworks:
January: Create a taxonomy for suggested tags as part of the `Conventions wiki
page
<https://wiki.openstack.org/wiki/Documentation/Markup_conventions>`_
(klevenstein, loquacities)
DONE January 15, 2015: Create jinja2 templates from Jekyll designs for:
* landing page and search (fifieldt)
DONE February 20, 2015: Create Sphinx template from Jekyll design for:
* content pages (annegentle)
DONE February: Replace static www jinja templates in openstack-manuals with
new design
Proof of concept with content:
February 15, 2015: Migrate DocBook to RST for these books in this priority
order:
* End User Guide
* Admin User Guide
Tracking on wiki page: https://wiki.openstack.org/wiki/Documentation/Migrate
February 28, 2015: Update our build infrastructure
so that Sphinx is used for publishing these documents:
* End User Guide
* Admin User Guide
February 20, 2015: Test templates across browsers to ensure parity with design:
* Chrome on Ubuntu, Fedora, Mac, Windows
* Firefox on Ubuntu, Fedora, Mac, Windows
March 2015: Test translation toolchain. Ying Chun Guo (Daisy) has agreed to
investigate.
DONE February 15, 2015: Update oslosphinx to have new openstackdocs theme:
Currently the theme name is "openstack." Reviewing the plan with Doug Hellman,
we can either keep the openstack theme and start one named "openstackdocs" or
update the openstack theme to be the new design. I prefer to name a new one
"openstackdocs" so that the current openstack theme which can indicate when a
project's doc is incubated remains.
DONE Updated to add: looking at the information architecture of the header,
it looks like it's best to have an openstack docs theme that doesn't
necessarily live in oslosphinx. Oslosphinx is used for
http://specs.openstack.org, http://docs.openstack.org/infra/system-config,
http://governance.openstack.org for example, and
http://docs.openstack.org/infra/system-config has modified the header so that it wouldn't
match the other sites. As a result, the plan is to keep the oslosphinx
theme with oslosphinx and create a theme in a separate repo named
openstackdocsthemes for application to all content published to
http://docs.openstack.org.
March (after proof-of-concept and CI is complete): Migrate DocBook to RST for
these books in this priority order:
* Cloud Administrator Guide
* Virtual Machine Image Guide
* High Availability Guide
* API Quick Start Guide
March: Once migrated, apply new openstackdocstheme template to these repos and
deliverables:
openstack-manuals:
* End User Guide
* Admin User Guide
* Cloud Administrator Guide
* Virtual Machine Image Guide
api-site:
* API Quick Start Guide
ha-guide:
* High Availability Guide
March: Remind projects to update their theme for /developer/ docs for:
* nova
* neutron
* glance
* keystone
* ceilometer
* cinder
* heat
* horizon
* ironic
* sahara
* swift
* trove
Dependencies
============
Foundation web developers hand-off of current design HTML and CSS files.
(Done)
Core olsosphinx reviewers helping with theme creation and reviews. (Done)
Translation team investigate and test translation toolchain.
Testing
=======
We need to test the new HTML design on these browsers/operating systems as a
priority:
* Chrome on Ubuntu, Fedora, Mac, Windows
* Firefox on Ubuntu, Fedora, Mac, Windows
Need to test translation toolchain.
Need to test PDF output if it's possible to get.
References
==========
* https://docs.google.com/document/d/1GGKTKHDMc8A0jerdv-K3ql0udnxMr-j4DlhL2Cj6kcw/edit?usp=sharing
* https://etherpad.openstack.org/p/docstopicsparissummit
* https://wiki.openstack.org/wiki/Documentation/Markup_conventions
* http://idratherbewriting.com/2012/12/04/what-does-every-page-is-page-one-and-include-it-all-filter-it-afterward-mean/

212
specs/kilo/move-driver-docs.rst
View File

@ -1,212 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
============================================
Proprietary driver docs in openstack-manuals
============================================
https://blueprints.launchpad.net/openstack-manuals/+spec/move-driver-docs
The Configuration Reference and Cloud Admin Guide include documentation for
various drivers. This spec clarifies the expectations and handling of such
documentation.
The shared goals for driver documentation includes:
- consistent documentation, comparable for each driver.
- version-independent documentation for each driver, meaning the
OpenStack version can change but the driver documentation can remain
the same.
- maintainable documentation for each driver that won't change much
over time and remains accurate.
- reviewable documentation for each driver.
Some benefits we see for this new approach are:
- more flexibility in changing detailed driver documentation on the
appropriate website.
- makes maintenance of detailed driver doc easier for contributing
driver writers since they can choose their source and publishing
chain that fits with their current workflow.
- reduces maintenance for core OpenStack documentation team.
The driver documentation for Compute, Storage, Networking, and
Databases will change as described with the goal of having accurate
documentation. This can be brief version independent information in
the OpenStack manuals with a link to a vendor page with full details
or full version.
Problem description
===================
Many OpenStack projects include drivers to support specific hardware
or software.
Examples are:
* Cinder: block storage drivers
* Neutron: network plug-ins
* Nova: hypervisors
* Trove: Different databases
Many of these drivers are hardware or software specific and can only
be documented by the third-party driver vendor. Some vendors have
great in-tree documentation and update it regularly, others have none
or only outdated documentation. Many vendors have already on
their web page documentation about the drivers, this spec proposes to
move the documentation to the vendor web pages and simply link to
them.
The spec also documents requirements for full documentation as part of
OpenStack manuals.
This will reduce work for both documentation team and vendor drivers
and give clear requirements.
Proposed change
===============
The documentation team will fully document the reference drivers as
specified below and just add short sections for other drivers. If a
vendor wants to document their driver, they are invited - but not
forced - to include their documentation in the Configuration
Reference if they commit to maintain the documentation. However,
other documentation (including the Cloud Admin Guide and Networking
Guide) will not contain content for third-party drivers. In these books,
where third party drivers exist, add the statement: "For other drivers,
see chapter X in the Configuration Reference Guide".
Guidelines for drivers that will be documented fully by the OpenStack
community in the OpenStack documentation:
* The complete solution must be open source and use standard hardware
* The driver must be part of the respective OpenStack repository
* The driver is considered one of the reference drivers
For documentation of other drivers, the following guidelines apply:
* The Configuration Reference will contain a small section for each
driver, see below for details
* Only drivers are covered that are contained in the official
OpenStack project repository for drivers (for example in the main
project repository or the official third-party repository).
If a vendor wants to add more than the minimal documentation, they
need to commit to the following guidelines:
* Assign an editor that is responsible for the content.
* Review and - if necessary - update their driver for each release
cycle.
With this policy, the docs team will document in the Configuration
Reference at least the following drivers:
* For cinder: volume drivers: document LVM and NFS; backup drivers:
document swift
* For glance: Document local storage, cinder, and swift as backends
* For neutron: document ML2 plug-in with the mechanisms drivers
OpenVSwitch and LinuxBridge
* For nova: document KVM (mostly), send Xen open source call for help
* For sahara: apache hadoop
* For trove: document all supported Open Source database engines like
MySQL.
Default section format for external drivers
-------------------------------------------
For each external driver, we want to document briefly the driver in a
way that is version independent and include the current configuration
options.
Each section should follow this format:
* A short paragraph explaining the driver.
* A link with detailed instructions to the vendor site (if there is one)
* A default paragraph like::
Set the following in your cinder.conf, and use the following options
to configure it.
volume_driver = cinder.volume.drivers.smbfs.SmbfsDriver
* And finally the autogenerated configuration options
Driver vendors can send in patches for these or create bugs.
Full documentation by vendors
-----------------------------
If a vendor wants full documentation in the Configuration Reference,
they have to add to the `wiki page
<http://wiki.openstack.org/Documentation/VendorDrivers>`_ a contact
editor that will take care of the vendor driver documentation. The
Documentation team will assign bugs to the contact person, include the
contact person in reviews for the vendor driver, and expects timely
responses.
If vendor driver documentation becomes outdated and the contact person
is not reacting to requests, the Documentation team will change the
full documentation to a minimal version.
The documentation team will review vendor drivers and ensure that the
various driver documents follow a consistent standard.
Alternatives
------------
* Keep status quo: Add all drivers to the Configuration Reference.
* Remove drivers, do not link to them at all - or just link to a
single wiki page.
* Have minimal documentation for all drivers only. This was the
initial idea but rejected since some vendors do not have
documentation on their own.
Implementation
==============
The work will be done in three steps:
#. In the Configuration Reference, bring all driver sections that
are currently just "bare bones" up to the standard mentioned.
#. Work with third-party drivers to convert existing documentation
in the Configuration Reference to the new standard.
#. Purge third-party driver content from other documentation such
as the Cloud Admin Guide.
Assignee(s)
-----------
Entire documentation team
loquacities - informing vendors
Work Items
----------
* Inform third-party driver contacts about change (note that we
have to make this spec known to them earlier to get input on it as
well)
* Ask vendor drivers to assign a contact person and give deadlines.
* Add minimal content for drivers that have no content right now.
* Enhance content (based on suggestion by driver vendors)
* Purge third-party driver content from other documentation.
Dependencies
============
None.
Testing
=======
References
==========
https://etherpad.openstack.org/p/docstopicsparissummit

151
specs/kilo/openstack-firstapp.rst
View File

@ -1,151 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
========================================
Writing your First OpenStack Application
========================================
Problem description
===================
Currently, OpenStack is missing documentation similar to other Python
projects, that introduces a new user to the API. One well known "first
app" tutorial in the Python community is the Django web framework's
`tutorial <https://docs.djangoproject.com/en/dev/intro/tutorial01/>`_.
Proposed change
===============
A guide has been written by members of the Application Ecosystem WG
that introduces the OpenStack API, using a non-trivial Python application
that serves as a teaching tool - similar to the poll app in the
equivalent Django tutorial.
Alternatives
------------
None
Implementation
==============
This book has been written for software developers who wish to deploy
applications to OpenStack clouds.
We've assumed that the audience is an experienced programmer, but that
they haven't necessarily created an application for cloud in general, or
for OpenStack in particular.
In addition to learning to deploy applications on OpenStack, the reader
will also learn some best practices for cloud application development.
This tutorial actually involves two applications; the first, a fractal
generator, simply uses mathematical equations to generate images.
However, really, it's just an excuse; the real application is the code that
enables the reader to make use of OpenStack to run it. That application
(and therefore this guide) includes:
* Creating and destroying compute resources.
* Cloud-related architecture decisions, such as microservices and modularity
* Scaling up and down to customize the amount of available resources.
* Object and block storage for persistance of files and databases.
* Orchestration services to automatically adjust to the environment.
* Networking customization for better performance and segregation.
* A few other crazy things we think ordinary folks won't want to do ;).
The guide has been written with a strong preference for the most common
API calls, so it will work across a broad spectrum of OpenStack versions.
In addition, the authors have paid special attention that the first 3 sections
should work almost regardless of OpenStack cloud configuration (basically
Nova, Keystone and Glance are the only requirements, but neutron will be used
if installed).
Repository Location
-------------------
This content should be published to developer.openstack.org.
The content created during the sprint should be separated from the app.
The content created during the sprint documents how to use the OpenStack API
and several OpenStack SDKs and the app is only an example use case. In theory
the used app (Faafo at the moment) can be replaced in the future (or maybe we
want to add a second use case) by an other app.
Additionally, the focus of the documentation placed inside the repository of
the app is different from the focus of the content created during the sprint.
The documentation inside the repository of the app describes how to use
the app itself (how to create a development environment, example outputs, ..),
not how to use OpenStack SDKs and the OpenStack API.
As such, content will live in ``openstack/api-site`` repository like
other documents published to http://developer.openstack.org. Therefore
the review team will be the standard docs reviewers for this
repository.
Multi-SDK support
-----------------
The guide has been written so that support for multiple SDKs is a core part of
its publication. Initial sections have been written for libcloud, and section1
is also available for fog. The design philosophy is that the same prose can be
used, with code samples swapped.
Assignee(s)
-----------
* Sean M. Collins (sean@coreitpro.com)
* Tom Fifield (tom@openstack.org)
* James Dempsey (jamesd@catalyst.net.nz)
* Nick Chase (nchase@mirantis.com)
* Christian Berendt (berendt@b1-systems.de)
Work Items
----------
* Write content during the sprint
* Add standard build jobs
* Standard content review
* Prominently link the content on developer.openstack.org
Dependencies
============
None
Testing
=======
The guide is written in such a way that all examples can
be run by the reader, and steps have been taken to verify that
all content is valid.
To date, libcloud sections 1-3 have been tested by at least 7 people on
7 different clouds that the authors are aware of, and the remaining
sections with samples have been tested on at least 3 different clouds.
Fog in section1 has only had testing on one cloud, and should not be
published until both section 1-3 is completed as a minmum and additional
testing has been performed.
The testing process for this guide is similar to the install guide.
A tester should take the role of a 'naive' reader, following the guide's
instructions exactly with no deviation. Any instructions that did not work,
or are too difficult to follow should be noted as bugs and fixed.
References
==========
* `[Openstack-operators] Fostering OpenStack Users <http://lists.openstack.org/pipermail/openstack-operators/2014-December/005788.html>`_
* `Application Eco WG - meeting - "first app tutorial" <https://www.youtube.com/watch?v=ahc5IsUdeK0>`_

106
specs/kilo/training-guides-icehouse-release.rst
View File

@ -1,106 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
====================================
Icehouse release for training guides
====================================
https://blueprints.launchpad.net/openstack-training-guides/+spec/training-icehouse-release
Training guides is ready to release Icehouse content. As per our discussions
during the Kilo design sessions in Paris, the team came to a common conclusion
to transition from XML books to RST presentations for delivering training
content more efficiently and to eliminate duplication of the content.
Advantages:
- Easy to transition from XML to RST.
- XML content will still be accessible for the current training sessions.
- Repetition of content from the manuals repository will be eliminated.
- Easier to get in track with the current release cycle of OpenStack.
- Maintain release cycle in sync with OpenStack releases.
Note: Etherpad discussions for Kilo summit:
https://etherpad.openstack.org/p/training-guides-kilo-summit
Problem description
===================
A detailed description of the problem:
* XML content is to be archived and deleted.
* Migrate from XML book format to RST presentation format.
* Keep the existing content for supporting on-going training sessions.
* Publish current XML content to Icehouse branch only.
* Other releases like Juno, Kilo will be published using RST based slides.
* In future Juno, Kilo branches will be created as required for publishing the
newer releases for training guides.
Proposed change
===============
* Freeze the master branch and branch it for Icehouse.
* Add Icehouse watermark to the XML content.
* The XML content will reside in the Icehouse branch for training guides.
* XML content will not be under active development and mostly for archival
purposes for supporting ongoing training sessions using the current content.
* There will be no XML content in the master branch after the release.
* Master branch will only contain RST files.
Alternatives
------------
* Use git history to point to the given Icehouse release instead of branch.
This has multiple issues:
- It may create confusion for trainers (our end-users).
- This will only serve the developers of this project.
- Difficult to publish newer releases.
* Keep XML and RST files side by side.
- This alternative is not advisable as it has multiple issues with XML
cross-referencing and should be avoided at all costs.
Implementation
==============
Assignee(s)
-----------
dguitarbite
Work Items
----------
* Freeze master branch for training guides repository.
* Create a stable/icehouse branch based on the current master branch.
* Update docs.openstack.org/icehouse/index.html page to point to
/icehouse/training-guides/.
* Change publish process in icehouse branch (pom.xml, tox.ini) in the
stable/icehouse branch.
* Remove XML content from openstack/training-guides master repo.
* Add redirects from docs.openstack.org/training-guides/ to
docs.openstack.org/icehouse/training-guides.
* Change publish process in master branch to publish to
docs.openstack.org/trunk/training-guides which include build results of
RST source content.
* Update docs.openstack.org/trunk/index.html page in master branch to link to
build results of the RST content.
Dependencies
============
None.
Testing
=======
References
==========
https://etherpad.openstack.org/p/training-guides-kilo-summit

90
specs/kilo/training-guides-osbash-color.rst
View File

@ -1,90 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Color support for osbash
==========================================
https://blueprints.launchpad.net/openstack-training-guides/+spec/osbash-color-support
Color variation to highlight messages and enhance readability while running
osbash scripts. Make this color variation compatible on most operating
systems - linux, OS X mainly.
Advantages:
* Enhances Readability
* Easier to debug
* Better understanding of sequence of events while running the scripts
* Adds color code to different types of messages eg. error, warning messages
* Adds to the aesthetics when running scripts
Problem description
===================
A detailed description of the problem:
* Current scripts are mono-colored and do not provide sufficient readability
* Assigning different colors for different types of messages will
* improve readability while running scripts
* highlights the problems
* easier debugging
* help track the sequence of events
* Assigning background color to console while script execution will
* provide uniform appearance across all consoles
* uniform color contrast
* Support will be provided for most operating systems that run osbash (linux,
OS X)
* Target audience will be deployers
Proposed change
===============
* Implementing a colorizer for osbash scripts
* Making it compatible across linux and OS X
* Having an option to change background color
Alternatives
------------
Running the existing scripts which have a mono-colored output
Disadvantages:
* Does not highlight different types of messages which help make the running
scripts more readable and easier to debug
* Difficult to follow the sequence of events while the script runs
Implementation
==============
Assignee(s)
-----------
Primary assignee:
sayalilunkad
Other contributors:
None
Work Items
----------
* Devise color code for different type of messages and background
* Color code for background to be made optional
* Implement colorizer to assign these colors
* Make compatible across linux, windows and OS X
Dependencies
============
None
Testing
=======
Run the scripts to check if the colorizer assigns the designated colors to
the output of the script.
References
==========
None

437
specs/liberty/api-site.rst
View File

@ -1,437 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
================================
Rework API Reference Information
================================
The blueprint we'll use to track this work supersedes prior blueprints that are
listed in the References section.
https://blueprints.launchpad.net/openstack-manuals/+spec/api-site
The API Reference site needs an update and better methods for maintaining and
providing accurate information for application developers using different cloud
provider's cloud resources.
Problem description
===================
With this blueprint we want to solve the following problems:
* API reference information has been historically difficult to maintain using
community or company resources due to the specialized nature of both the
tools and the REST API knowledge.
* API reference information needs to be sourced where API writers, API
developers, contributor developers, and the API working group members can
review together.
This blueprint should provide a major rework of the way we provide upstream API
reference information to cloud users. The intended audience targets application
developers and SDK developers who need precise and accurate information about
each service's REST APIs. This is not API information for internal APIs such as
the RPC API used by the Compute project (nova) for scheduling compute hosts,
for example. These references are used to build a correct API call with the
correct request parameters and double-check your cloud provider's results
against the results you see on screen when you make a call.
There are currently 915 GET/PUT/POST/DELETE/PATCH calls documented on the
OpenStack API Complete Reference site at
http://developer.openstack.org/api-ref.html.
Currently, the API reference is in a separate repo, api-site. In the kilo
release (Nov14-Apr15) we moved all "narrative" information to the repo of the
project's choosing. For most projects, that location was the <project>-spec
repo. For Compute and Object Storage, it was their project's doc/source repo.
The API reference information remained in api-site repo.
With the growth of teams with REST APIs to more than 20, we need to strictly
enforce where API reference information is maintained and built from.
Ideally we will enable teams to review while bringing all the sources together
into one consumable, readable guide to the various services's REST APIs. These
should be handy Developer Guides that provide a unified view of
separately-sourced information.
Now that we've described the problem and a brief discussion of the vision,
let's talk about solutions.
Scope for Liberty release
-------------------------
For the first set of developer guides sourced across multiple repos with
automation for reference information, the scope will be limited to
infrastructure services used most based on the most recent User Guide survey.
* Identity v2.0
* Compute v2
* Block Storage v2
* Image service v2
* Networking v2.0
However, while we are working on this proof-of-concept, the WADL needs to be
maintained so that we have a benchmark comparison point for quality testing
purposes.
Proposed change
===============
We want to ensure that we use the current project's source code to create
the most accurate and up-to-date API reference documentation. We also want to
ensure reviews are in the repo where the best reviewers are keeping vigil.
So, as a proof of concept, write a Python library that uses the Python routes
library to inspect the source code and output a standard such as Swagger
version 2 that can be used for doc output or mock testing of the requests and
responses so that we can eventually build a continuous test layer that ensures
backwards compatibility for examples even when the code changes.
Here is an overview of the envisioned process:
#. Do a git clone command to get a copy of the project's repo.
#. Run the automation script with some config info in the api-paste.ini file
to create Swagger.
#. Repeat and test for each project.
Here is a list of what Web Server Gateway Interface (wsgi) frameworks are in
use for OpenStack projects:
- Ironic: pecan, wsme
- Nova: routes, JSONSchema
- Cinder: routes
- Glance: routes, JSONSchema
- Neutron: routes
- Trove: routes
- Heat: routes
- Saraha: flask
- Swift: None
- Keystone: routes
- Ceilometer: pecan
- Barbican: pecan
For reference, these projects are already documented in the `openstack/api-site
repository <https://github.com/openstack/api-site/>`_:
* ceilometer: Telemetry or Telemetry module
* cinder: OpenStack Block Storage (two versions)
* glance: OpenStack Image service (two versions)
* heat: Orchestration or Orchestration module
* keystone: OpenStack Identity (two versions)
* neutron: OpenStack Networking
* nova: OpenStack Compute (two versions)
* sahara: Data processing service for OpenStack
* swift: OpenStack Object Storage
* trove: Database service for OpenStack
API docs elsewhere or unknown state:
* barbican: Key management service
* ironic: Bare metal service
* tripleo: Deployment
* zaqar: Message service
* designate: DNS service
* magnum: Containers service
* murano: Application catalog
* congress: Non-domain specific policy enforcement
* rally: Benchmark service
* mistral: Workflow service
Requirements include:
Authoring: Information and source must be maintained and reviewed by project
developers with API working group informed and doc team providing support.
Authoring: API reference information could be auto-generated with strings
stored in the code or reviewed and written collaboratively. For more info,
review the :ref:`overview-of-standards` below.
Authoring: API reference information review should use the APIImpact and
DocImpact flags.
Authoring: Need an open-source toolchain for authoring.
Output: Output must offer a great experience for SDK developers and
application developers consuming OpenStack cloud resources. Optionally, it
would offer a "try it out" sandbox for each call against TryStack when using
authenticated credentials.
Output: Output should indicate which version of OpenStack will support a
particular API version, and within extensible APIs like Compute and Identity,
indicate which version a particular extension is available with.
Output: Since we may need a phased approach for timing and scoping, should work
with current docs such as with redirects or integrated displays.
Build: Must be automated based on Gerrit review and workflow.
Scope: Must be viable within six month release period.
Optional features:
Build: Optionally, build pieces that any cloud provider could then consume and
re-use in their customer documentation.
Contract validation: Optionally, provide validation of requests and
responses as valid and would work against a public cloud endpoint.
Compilation of changes: Optionally, provide a list of changes to help
reviewers discover wording that could be fixed, inconsistencies in examples,
parameter naming, potential for better human grouping and so on.
Conceptual API information
--------------------------
As noted above, ideally we enable teams to write and review API information
while bringing all the sources together into one consumable, readable guide.
The work done last release to put the "narrative" information, such as rate
limits, versioning, and so on into each project's managed repository should be
reused for these Developer Guides.
For an interim step, we can start publishing the RST-sourced information to
http://developer.openstack.org/api-guide/compute
from the http://git.openstack.org/cgit/openstack/nova/tree/doc/source/v2
information. Publishing as separate items does mean needing to add a separate
index.rst and conf.py build for each of the services that has these types of
conceptual documents.
Also, add a new column to the developer.openstack.org landing page that links
to conceptual information for each service in a column next to API Reference.
These are the current links to API conceptual information:
http://docs.openstack.org/developer/nova/v2/index.html
http://docs.openstack.org/developer/swift/#object-storage-v1-rest-api-documentation
http://specs.openstack.org/openstack/glance-specs/#image-service-v2-api
http://specs.openstack.org/openstack/glance-specs/#image-service-v1-api
http://specs.openstack.org/openstack/keystone-specs/#v3-api
http://specs.openstack.org/openstack/keystone-specs/#v2-0-api
http://specs.openstack.org/openstack/neutron-specs/#api-specs
http://specs.openstack.org/openstack/cinder-specs/#volume-v2-api
By building and linking more prominently we hope to add to the collection of
helpful information for application and SDK developers.
.. _overview-of-standards:
Overview of standards
---------------------
The reference portion of this documentation should follow an industry standard.
REST API documentation has evolved over the years and a few standards have
recently become popular:
Swagger
Community-maintained standard, open-source tooling. Allows for
inclusion of content similar to our current entities. To output the
information you must run a server that renders the content. Current
community-maintained specification for content is version 2, see
https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md.
Supported by SmartBear Software.
RAML
Community-maintained standard, proprietary tooling unless you just edit
in text, but then how do you validate? RAML specification found here:
http://raml.org/spec.html. Allows for inclusion of content similar to our
current WADL entities for reuse of content. Based on YAML, supported
and provided by MuleSoft.
API Blueprint
The API Blueprint standard was started by Apiary, a company that specializes
in API design and documentation, but they do accept patches
from the community. The JSON and YAML specification is at
https://github.com/apiaryio/api-blueprint-ast. We could write a JSON schema
to add to the standard "asset element" based on
https://github.com/apiaryio/api-blueprint-ast#asset-element. However it
currently does not support a data structure that will allow us to have
multiple request/response combinations for the same endpoint.
WADL
Currently all the reference information is housed and maintained in
openstack/api-site in WADL files. We have a `WADL2Swagger tool <https://github.com/rackerlabs/wadl2swagger>`_
which has been run on our current WADL files. The `resulting Swagger files <http://rackerlabs.github.io/wadl2swagger/openstack.html>`_ can be used for
comparison and testing purposes.
With the Python routes approach, we could first write to the Swagger 2.0 spec
but then write another lexer for RAML if needed.
JSON schema could be required for our API requests validation, to see if the
contract is being upheld. JSON Schema is a JSON media type for defining the
structure of JSON data, such as a request from a REST API service. JSON Schema
provides a contract for what JSON data is required for a given application and
how to interact with it. For example, request parameters, many of which are
defined as "plain" parameters, and some of which have multiple array-based
needs in the request that would have to be defined with JSON schema.
Example: Here's a sample request for adding personality to a Create Server
POST /v2/{tenant_id}/servers::
"personality": [
{
"path": "/etc/banner.txt",
"contents": "ICAgICAgDQo...mQgQmFjaA=="
}
]
Considerations
==============
Russell Sim has done a proof of concept for Volume API v2. He can upload an
example for the rest of the team to start working on. He investigated using
httpdomain, but it seems that it would require depending on Sphinx in
production, angering packagers and operators alike. Instead he is making
a compatible parser written in docutils. That way we hopefully can reuse the
documentation to build with Sphinx later, but not have Sphinx as a runtime
dependency.
The `CORS cross-project specification <https://review.openstack.org/#/c/179866/>`_
should help with display of results using AngularJS as
it's a similar idea.
Identity v3 has the most calls in the core with 74, but Compute v2 plus
extensions has over 120 calls.
Currently the openstack/api-site repo that creates the API reference
information documents the last two stable releases. Our current policy is not
to merge changes to the master version of any API because end users would not
typically have access to a cloud that has that change.
For this new approach in this spec, examples are generated based on walking
through the source, so our tool would have to first apply to cinder
stable/juno and output, for example. Next, apply the tool to the cinder
stable/kilo branch and generate output. For testing purposes, the tool can be
applied against cinder master branch and flag when a backwards-incompatible
change would occur or flag when samples changed and release notes should note
the change. Versions and microversions should be displayed per call.
Alternatives
------------
Could keep what we currently have in api-site and WADL. However this requires
the continued use of clouddocs-maven-plugin for builds, which currently has no
maintainers.
Wait for a standard to emerge that supports microversions, multiple responses,
and all the features we need for our myriad API designs. None of the current
standards (WADL, Swagger, RAML) support microversions so we need to forge our
own path to ensure future maintainability and serving app devs writing code for
OpenStack clouds.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
annegentle
Other contributors:
cberendt
russellsim
Work Items
----------
Proof of concept automating API reference information with Volume v2 service.
Proof of concept aggregating information across separate repos in their
respective doc/source directories.
Web design and development of templates for new developer guide.
Information architecture for where the deliverables should be published on
http://developer.openstack.org/.
Fix WADL where inconsistencies are discovered.
Write a JSON Schema for modified Swagger (Swaggerish) to support multiple
request/response types at the same URL, such as Orchestration actions resource:
http://developer.openstack.org/api-ref-orchestration-v1.html#stack_action_suspend
http://developer.openstack.org/api-ref-orchestration-v1.html#stack_action_resume
Or the Compute server actions resource:
http://developer.openstack.org/api-ref-compute-v2.html#compute_server-actions
Define documentation that is included in a Swagger Tag. For example, there
exists a lot of narrative or conceptual information in the WADL and DocBook
that we need to integrate into an overall dev guide. We could develop a Tag
hierarchy with a naming scheme like:
server
server::actions
server::metadata
server::actions
Then use the Tag to design the front-end.
Surface the existing conceptual information by publishing existing content to
developer.openstack.org/api-guides/<servicename>.
Migration work items:
Delete WADL files in api-site/api-ref once replacement is complete.
Create a feature branch for api-site
Prepare the developer.openstack.org website for the transition including
DevStack installation, CORS support, and an overall information architecture
for developer guides.
Create a front-end design for presenting the information. Two POCs:
Default Swagger UI http://fairy-slipper.russellsim.org/swagger-ui/
Stripe-like Swagger UI (from jensoleg):
http://fairy-slipper.russellsim.org/swagger-ui-jensoleg/
Dependencies
============
* In order to place this functionality in oslo, we'll need the co-operation of
oslo reviewers.
* The API Working Group is following closely and will help with ensuring the
solution meets our needs.
Testing
=======
Output should be tested for cross-browser, cross-operating-system
compatibility.
Generating the Swagger should not require Sphinx as a run-time, to ensure that
we do not introduce unwanted global dependencies.
References
==========
Previous unimplemented blueprints related to this spec:
* https://blueprints.launchpad.net/openstack-manuals/+spec/autogenerate-api-reference
Generating API reference information and samples is a good way forward.
However, we'll supercede this blueprint with this implementation spec as that
blueprint does not have a detailed spec associated with it.
* https://blueprints.launchpad.net/openstack-manuals/+spec/api-samples-to-api-site
Moving content to project repos would be the opposite moving direction
and may work perfectly well for this use case.
* https://blueprints.launchpad.net/openstack-manuals/+spec/api-try-it-out
I'd see this as a stretch goal, not necessarily required for the main
goal of making contributions and maintenance better going forward.
Additional information:
* API Archaeology: Complexity and sizing of an interface
http://justwriteclick.com/2015/01/12/api-archaeology-complexity-and-sizing-of-an-interface/
This blog post gives counts as of the January post date. As of April 27,
2015 the counts are now 915 calls.
* List of services with REST APIS:
http://git.openstack.org/cgit/openstack/governance/tree/reference/projects.yaml
* Issues with WADL2Swagger: The underlying issue is that Swagger
definitions itself should require JSON schema to be useful and contractual.
https://github.com/rackerlabs/wadl2swagger/issues/8
* November 2014 User Survey Data http://superuser.openstack.org/articles/openstack-user-survey-insights-november-2014
* April 2015 User Survey Data (app devs) http://superuser.openstack.org/articles/openstack-application-developers-share-insights
* API Docs Working Session Etherpad https://etherpad.openstack.org/p/Documentation__API_Work_Session
* Pecan decorator proof-of-concept for creating swagger https://github.com/elmiko/pecan-swagger

84
specs/liberty/arch-guide.rst
View File

@ -1,84 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
======================================
Architecture Design Guide Improvements
======================================
https://blueprints.launchpad.net/openstack-manuals/+spec/arch-guide
Review, edit, and reorganize the Architecture Design Guide.
Problem description
===================
The Architecture Design Guide has not been thoroughly reviewed since its
creation. This has led to the following issues:
- language and syntax not in accordance with our conventions
- improvable information architecture
- duplication of content
Proposed change
===============
- Reorganize guides to improve presentation of existing content
- Clean up existing content where necessary and remove duplication
- Identify information gaps and raise bugs where necessary
This work is a precursor to converting this guide from Docbook XML to RST in a
future release.
Alternatives
------------
- Leave the guide as it is
- raise bugs against each individual section that requires improvement
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Brian Moss (bmoss)
Other contributors:
Documentation Swarm attendees
Work Items
----------
The bulk of this work is expected to be completed at the upcoming documentation
swarm taking place in Brisbane AU on August 13-14. See :ref:`References`.
- Rework the abstract to clearly identify the audience and purpose of the book
- Reduce duplication in the guide as much as possible.
- Edit for consistency and adherence to our conventions
- Move sections as required to improve information architecture
Dependencies
============
None
Testing
=======
Standard documentation review process.
.. _References:
References
==========
`Documentation Conventions <https://wiki.openstack.org/wiki/Documentation/Conventions>`_
`Swarm Website <http://openstack-swarm.rhcloud.com/>`_

86
specs/liberty/audio-visual.rst
View File

@ -1,86 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Audio Visual training videos
==========================================
https://blueprints.launchpad.net/openstack-training-guides/+spec/training-guides-videos
To increase the impact of the training guides, videos will be added to the
training guides. These videos will try to cover major OpenStack deployments
and installation of OpenStack modules so that the trainees do not get stuck.
Link to training-guides YouTube channel:
https://www.youtube.com/user/trainingguides/videos
Problem description
===================
A detailed description of the problem:
* Target audience will be trainees, deployers and students
* Complements the documents
* Clears any ambiguity present in the documents by providing actual
demonstration
Proposed change
===============
* Priority of creation of videos would vary as per needs and demands
from the trainees.
* Main focus would be on covering the major deployments with respect to the
developers guide, associate guide, operator guide and architect guides.
* Scope of the content covered by the videos would span over the content of
the training-guides.
* Videos will be made as modular as possible to make them reusable.
* If the license permits, content from summit videos can be edited to be used
for audio-visual content.
Alternatives
------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
sayalilunkad
Other contributors:
shilla-saebi
Work Items
----------
* List videos by priority, to be made for kilo
* Write scripts for the videos to be made(Done on `etherpad
<https://etherpad.openstack.org/p/openstck-training-guides%28Audio_Visual_Content%29>`_)
* Scripts will be reviewed by team
* After approval, videos will be created
* Videos will be hosted on the `training-guides channel on YouTube
<https://www.youtube.com/user/trainingguides/videos>`_
Dependencies
============
None
Testing
=======
None
References
==========
* YouTube channel for training-guides:
https://www.youtube.com/user/trainingguides/videos
* Etherpad discussion:
https://etherpad.openstack.org/p/openstck-training-guides%28Audio_Visual_Content%29

173
specs/liberty/docs-contributor-guide.rst
View File

@ -1,173 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=========================================
OpenStack Documentation Contributor Guide
=========================================
https://blueprints.launchpad.net/openstack-manuals/+spec/docs-contributor-guide
Problem description
===================
Based on the docs contributors experience and feedback, the information for
the documentation contributors located on wiki sometimes contains outdated
info and can be improved by restructuring and supplementing.
As we are treating our documentation as the code and willing others to do so,
we need to relocate all the conventions, how to instructions and any docs
contributor-related things to the place that fits as a single-entry, full,
and neatly organized guide that answers questions that arise in the docs
creation workflow.
The wiki is definitely not much convenient, it has narrowed functionality and
lacks a number of features that have become essential part of any internet user
nowadays, such as search, proper navigation, and some others.
Moving things around will noways influence its openness to the community or
make the conventions less flexible. This will only unify and simplify the
process.
Proposed change
===============
We propose the creation of the Documentation Contributors Guide
targeted at the contributors to the OpenStack documentation that will cover:
* Workflow (= Quickstart)
* Workflow (= HowTo)
* Licencing and copyrighting - an outline with links to:
* http://www.openstack.org/brand/
* https://review.openstack.org/static/cla.html
* https://wiki.openstack.org/wiki/How_To_Contribute#Contributors_License_Agreement
* Markup conventions (RST - first priority, DocBook)
* Terminology and writing syntax conventions
* Screenshots and topologies conventions
* Documentation structure
* Team structure
Documentation Contributors Guide: RST
Here is the table that lists the existing wiki content and outlines how
it should be reworked from the contributor perspective:
.. list-table::
:header-rows: 1
* - Wiki page
- User story
* - `HowTo <https://wiki.openstack.org/wiki/Documentation/HowTo>`_
- As a docs contributor, I would like to know in details: what tools are
required; how to edit, check builds and commit the changes; how to amend
a review-in-progress, cherry-pick and make changes to a stable branch;
how to work with launchpad bugs and review patches.
* - `HowTo/FirstTimers <https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers>`_
- As a docs contributor, I would like to have a quickstart guide with
a suite of basic instructions on how to commit the change, respond
to requests and troubleshoot.
* - `Documentation/Builds <https://wiki.openstack.org/wiki/Documentation/Builds>`_
and `Documentation/ContentSpecs <https://wiki.openstack.org/wiki/Documentation/ContentSpecs>`_
- As a docs contributor, I would like to clearly understand what content
goes where and where to get the sources (+ why the spec is required and
how to create it)
* - `Documentation/Conventions <https://wiki.openstack.org/wiki/Documentation/Conventions>`_
- As a docs contributor, I would like to be aware of all the writing style
guidelines that should be followed by the contributors to the OpenStack
documentation.
* - `Documentation/Markup_Conventions
<https://wiki.openstack.org/wiki/Documentation/Markup_conventions>`_
- As a docs contributor, I would like to be aware of all the XML/RST
markup guidelines that should be followed by the contributors
to the OpenStack documentation.
* - `Documentation/JSON_Conventions <https://wiki.openstack.org/wiki/Documentation/JSON_conventions>`_
- As a docs contributor, I would like to be aware of all the JSON
guidelines that should be followed by the contributors to the OpenStack
documentation.
* - `Documentation/Structure <https://wiki.openstack.org/wiki/Documentation/Structure>`_
- As a docs contributor, I would like to be aware of how to name and
arrange files and directories in books.
.. note:: `HowTo <https://wiki.openstack.org/wiki/Documentation/HowTo>`_
and `HowTo/FirstTimers <https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers>`_ are also covered
by http://docs.openstack.org/infra/manual/developers.html.
We should not duplicate but reference to it there.
Implementation
==============
Work Items
----------
#. Create a separate wiki page to keep all the related details on the
project.
#. Work out the detailed and well-structured table of contents (on wiki).
#. Create, and adjust a separate directory in openstack-manuals for the guide.
#. Revise, move, and delete the existing (wiki) content.
#. Create new content, which is required from the contributor perspective,
for example, Screenshots and topologies guidelines.
#. Make sure not to duplicate the content from
http://docs.openstack.org/infra/manual/developers.html, but reference
to it if it is required.
#. Add the link to the docs contribution workflow to the Infra Manual.
Assignee(s)
-----------
Primary assignee:
Olga Gusarenko, `ogusarenko <https://launchpad.net/~ogusarenko>`_
Other contributors:
* Alexander Adamov, `aadamov <https://launchpad.net/~aadamov>`_
* Olena Logvinova, `ologvinova <https://launchpad.net/~ologvinova>`_
* Maria Zlatkova, `mzlatkova <https://launchpad.net/~mzlatkova>`_
Testing
=======
Feedback from the docs contributors
References
==========
* Add the link to the project wiki page.

174
specs/liberty/ha-guide.rst
View File

@ -1,174 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
====================================
High Availability Guide Improvements
====================================
https://blueprints.launchpad.net/openstack-manuals/+spec/improve-ha-guide
This guide provides OpenStack cloud operators with configuration
details and best practices guidelines for creating a highly-available
cloud environment. This is critically important if OpenStack is to
"win the enterprise". This restructure will offer readers a more
logical flow between an initial installation and adopting high
availability components for an OpenStack cloud. Additionally, it
should reduce the content maintenance burden of the Docs team in
general by reducing duplication. We’ve prepared a draft table of
contents for the `HA Guide restructure
<https://wiki.openstack.org/wiki/HAGuideImprovements/TOC>`__
along with starting notes for included content.
Problem description
===================
This will be an HA Installation Guide; information about how to manage an
existing HA environment (such as how to recover from a failed component) is
beyond the scope of this project.
The strategic assumptions are:
#. We assume that users have already built at least a "learning" OpenStack
environment following the information in the Install Guide before
they attempt to set up an HA environment. The HA Guide should be
targeted at users who have some experience installing OpenStack.
#. The HA Guide should be structured to parallel the Install Guide as much
as possible. This means that the installation information will be
structured sequentially, around the OpenStack components rather
than HA strategies (active/passive vs active/active). The
high-level flow is:
- HA Intro and Concepts
- Hardware setup
- Infrastructure prerequisites that we assume are in place before starting
an HA deployment or upgrade
- HA networking: neutron only (very high-level with handoff to Networking
Guide)
- HA configuration for Controller services
- HA configuration for Storage services, including brief discussion of the
advantages of Ceph and a handoff to Ceph documentation for configuration
details
- HA configuration for Compute node services
- Other HA configuration (ceilometer with MongoDB, heat, trove)
#. The HA Guide should heavily reference the Install Guide and will then
supplement that information. For example, "Install and configure the xx
component following the instructions in the Install Guide, then do these
additional configurations." This will minimize content duplication.
#. Similarly, we expect that the Networking Guide will handle
high-availability networking configuration and the HA Guide will
reference that material.
#. The HA Guide should emphasize a reasonable, standard deployment based on
open source components. We can provide some notes about alternatives as
appropriate (for example, using a commercial load balancer might be a
better alternative than relying on HAProxy).
#. In general, the HA Guide should only cover core OpenStack services.
Other projects (such as sahara and murano) should cover HA configurations
in their documentation.
#. The HA guide should cover all appropriate Linux distros/platforms.
#. We will reuse as much of the material in the existing HA Guide as
possible, with revisions to augment and update the information. The revised
document will be written in RST; existing content will be converted as it
is added to the new document.
#. Some attempt will be made to incorporate material for both the Juno and
Kilo releases, identifying configurations, etc that are different for these
releases.
Proposed change
===============
The guide should remain in the ha-guide repository with the set of
reviewers currently assigned. The guide should be re-written with the
assumptions outlined in the Problem description above.
The source may be set up to use `intersphinx
<http://sphinx-doc.org/latest/ext/intersphinx.html>`__ to support
copious cross-references between the HA Guide and the Install Guide.
If this is not possible, the guide must use HTML linking to accomplish
the same.
Alternatives
------------
- Maintain the current structure, splitting between active/active and
active/passive. This puts the onus on the user to figure out what to
do in what order.
- Fully incorporate HA configuration information into the Install
Guides. This would really complicate the process of creating and
maintaining the Install Guides and would defeat the goal of having
the Install Guides be easy to follow for people who are new to
OpenStack and may also be new to Linux.
- Create a comprehensive HA Install Guide that replicates relevant information
from the Install Guides. This would create a maintenance nightmare.
- Relegate all HA configuration information
to the documentation for the individual components.
This would make it very difficult for the user to get the "big picture"
about how to implement HA for an environment.
While we plan to have the details of HA for networking
and many non-core services covered in the documentation for those pieces,
we need a single document that details the process
of getting the major Controller services configured for HA
and provides a roadmap for all HA configuration.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
mattgriffin
Other contributors:
<launchpad-id or None>
Work Items
----------
Revise based on https://wiki.openstack.org/wiki/HAGuideImprovements/TOC.
Create build and automation for RST rather than DocBook especially considering
much of the content is new and the current Active/Active and Active/Passive
structure will be abandoned.
Structure in parallel with Install Guide.
Heavily rely on Networking Guide scenarios.
Dependencies
============
* May require tight linking with the Install Guide(s). Be sure to track
carefully with any blueprint for improvements to the Install Guide(s).
Testing
=======
Testing a high-availability cluster does require a lot of hardware and probably
a lab.
References
==========
* http://lists.openstack.org/pipermail/openstack-docs/2015-March/006058.html
* http://lists.openstack.org/pipermail/openstack-docs/2015-March/006012.html
* http://lists.openstack.org/pipermail/openstack-docs/2015-April/006225.html
* https://wiki.openstack.org/wiki/HAGuideImprovements/TOC

146
specs/liberty/installguide-liberty-debian.rst
View File

@ -1,146 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
============================================
OpenStack Liberty Installation Guide: Debian
============================================
https://blueprints.launchpad.net/openstack-manuals/+spec/installguide-liberty
The OpenStack Installation Guide for Debian requires a number of changes
and updates before it can be published to the OpenStack documentation site.
Problem description
===================
The following steps need to be taken before the OpenStack Installation Guide
for Debian can be re-published:
* Conversion to RST
* Testing and revision of content
Proposed change
===============
#. Because of the similarity between Debian and Ubuntu, most Debian users can
follow the Ubuntu installation instruction. Most Debian-specific
configuration content is expected to be maintained in the Debconf chapter.
.. note::
The debconf system is the general interface between Debian and its user.
It is used to change configuration directives of OpenStack services.
However, we understand that the goal is not to just teach how to install
OpenStack, but also to understand what should be configured in which
directive of what section of what file. Therefore, the Debconf chapter
will include explanations of the directives that the Debian
packages handle automatically.
To ensure that Debian users get the same level of understanding as other
users, the Debconf chapter will document the following elements:
* Debconf prompts
* The directive influenced by the prompt
* Screenshots showing the configuration results
* Note that this information can be used for pre-seeding and puppet
scripts as well.
#. Convert the Debconf chapter of Installation Guide to RST.
This chapter describes the following procedures:
* Setting up databases
* RabbitMQ credentials (login, pass, host)
* [keystone_authtoken] (login, pass, tenant and host)
* API endpoints
.. note::
These need to be in a single chapter, to avoid repeating the same
content for each service.
#. Convert `Install and Configure` section for each component to include
references to the Debconf chapter as an alternative way to
configure packages.
#. Use a `debian` tag to specify the conditional for Debian content
according to the main specification:
http://specs.openstack.org/openstack/docs-specs/specs/liberty/installguide-liberty-rst.html
You can find added tags here:
https://review.openstack.org/#/c/191516.
#. While RST migration will be going on, test the guide and report
bugs on launchpad.
#. Prepare the drafts to fix the bugs.
#. Once migration is done, review the fixes.
#. Once updated, raise a discussion to publish the Debian Installation Guide
on docs.openstack.org.
Alternatives
------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
aadamov
Other contributors:
karin-levenstein
Experts:
thomas
Work Items
----------
* Testing the Debian guide and find the differences between
Debian and Ubuntu guides that need to be converted specifically.
* Report bugs if found.
* Write fixes.
* Convert to RST Debian specific parts (in parallel with testing the Guide).
* Put fixes on review.
* Publish the guide on the main page.
Dependencies
============
The main dependency is on the main installation guide conversion described in
http://specs.openstack.org/openstack/docs-specs/specs/liberty/installguide-liberty-rst.html.
Testing
=======
The same procedures as specified in
http://specs.openstack.org/openstack/docs-specs/specs/liberty/installguide-liberty-rst.html.
References
==========
The plan and status of the Debian Installation Guide conversion
will be tracked in the `Etherpad
<https://etherpad.openstack.org/p/Debian_Install_Guide_-_Changes_ToDo>`_
Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with
[install-guide][debian] tags in the subject,
weekly `Installation Guide specialty team meeting
<https://wiki.openstack.org/wiki/Documentation/InstallGuide>`_,
weekly `documentation team meeting
<https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting>`_,
and potentially etherpads.
In addition, Debian Installation Guide meetings can be arranged on
Mondays at 13.00 UTC in Google Hangout to discuss the blocking issues.

118
specs/liberty/installguide-liberty-rst.rst
View File

@ -1,118 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
====================================================
OpenStack Liberty Installation Guide: RST Conversion
====================================================
https://blueprints.launchpad.net/openstack-manuals/+spec/installguide-liberty-rst
The OpenStack Installation Guide will be converted to RST.
DocBook will continue to be maintained in stable/kilo.
Problem description
===================
For the Liberty time frame, the following tasks need to be accomplished for
the Installation Guide:
* RST conversion
* Liberty installation updates and testing
This spec is primarily concerned with the RST conversion.
Proposed change
===============
Freeze development on the Installation Guide.
Convert Installation Guide to RST, concentrating on installation of core
services: nova, cinder, glance, keystone, neutron, swift.
Conditionals can be applied using :code:`:only:` or the ifconfig_
extension.
.. _ifconfig: http://sphinx-doc.org/ext/ifconfig.html
Conditional tags will be simplified as much as possible, grouping content
according to operating system group:
* ``obs``: openSUSE, SUSE Linux Enterprise Server
* ``rdo``: CentOS, Fedora, RHEL
* ``ubuntu``: Ubuntu
Plan for Debian install guide will be addressed in a separate spec.
Alternatives
------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* karin-levenstein
Other contributors:
* berendt
* dguitarbite
* jaegerandi
* ionosphere80
Work Items
----------
Freeze on updates in master.
Track changes in wiki_.
.. _wiki: https://wiki.openstack.org/wiki/Documentation/Migrate
Update our build infrastructure so that Sphinx is used for publishing the
Installation Guide.
Apply new openstackdocstheme template to the guide.
Dependencies
============
The main dependency is on docs.openstack.org infrastructure updates.
Testing
=======
We need to test the new HTML design on these browsers/operating systems
as a priority:
* Chrome on Ubuntu, Fedora, Mac, Windows
* Firefox on Ubuntu, Fedora, Mac, Windows
Need to test PDF output.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [install-guide]
in the subject, weekly Installation Guide `specialty team meeting`_,
weekly `documentation team meeting`_, and potentially etherpads.
.. _`specialty team meeting`: https://wiki.openstack.org/wiki/Documentation/InstallGuide
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
.. _`rst conversion discussion`: https://etherpad.openstack.org/p/Documentation__RST_Migration
.. _`Liberty blueprint discussion`: https://etherpad.openstack.org/p/Documentation__Blueprint_Work_Session

112
specs/liberty/installguide-liberty.rst
View File

@ -1,112 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
====================================================
OpenStack Liberty Installation Guide: Content Update
====================================================
https://blueprints.launchpad.net/openstack-manuals/+spec/installguide-liberty
After the RST conversion, change the network architecture and update
configuration options as Liberty approaches usability.
Refer to the Installation Guide RST conversion spec for more information
about the RST conversion.
Refer to the Installation Guide for Debian spec for more information about
the Debian guide.
Problem description
===================
For the Liberty time frame, the following tasks need to be accomplished for
the Installation Guide:
* Architectural changes for network paths
* Configuration changes
* Testing
Proposed change
===============
#. Change the architecture to remove nova-network path.
#. Change existing neutron path to use the Linux bridge agent.
#. Add a neutron path to implement provider networks with the Linux bridge
agent.
#. Update configuration items using a combination of the configuration
reference and packages as they become available for Liberty.
#. As time and resources permit, implement optional enhancements TBD.
Alternatives
------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
karin-levenstein
Other contributors:
berendt
dguitarbite
jaegerandi
ionosphere80
Work items
----------
Architectural
* Remove nova-network path.
* Change neutron conventional (tenant/external) network path from Open vSwitch
to Linux bridge agent.
* Add neutron provider network path with Linux bridge agent.
Configuration
* Update configuration items (TBD).
Dependencies
============
Liberty milestone or RC packages for each distribution supported by the
Installation Guide.
Testing
=======
* All distributions supported by the Installation Guide must complete
`testing`_ of at least core services (Identity, Image Service, Compute,
and Networking) and successfully launch an instance using both provider
and conventional (tenant/external) network paths. Distributions that do
not meet these criteria risk temporarily removal from publication.
.. _`testing`: https://wiki.openstack.org/wiki/LibertyDocTesting
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [install-guide]
in the subject, weekly Installation Guide `specialty team meeting`_,
weekly `documentation team meeting`_, and potentially etherpads.
.. _`specialty team meeting`: https://wiki.openstack.org/wiki/Documentation/InstallGuide
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
.. _`Liberty blueprint discussion`: https://etherpad.openstack.org/p/Documentation__Blueprint_Work_Session

96
specs/liberty/manila-config-ref.rst
View File

@ -1,96 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
========================================================
Add Shared File Systems (manila) to the Config Reference
========================================================
Launchpad blueprint:
https://blueprints.launchpad.net/openstack-manuals/+spec/manila-config-ref
Shared File Systems (manila) should be added to the Config Ref similar to
Block Storage (cinder).
Problem description
===================
Shared File Systems (manila) is not currently included in the
Configuration Reference. The documentation is currently kept in-tree
in the manila devref. Administrators using Block Storage, Object
Storage, and Shared File Systems would expect to find a similar
reference for all three projects in the Configuration Reference. The
automated configuration doc tools should be leveraged.
Proposed change
===============
The content would be similar to Block Storage in that it would have sections
to describe introduction, drivers, log files, and options. The drivers section,
however, would use shorter more stable descriptions of drivers and use
links to vendor web sites and in-tree vendor docs.
Automatically generated configuration tables should be used where
possible.
Alternatives
------------
The amount of vendor driver documentation that should be included
in the Configuration Reference is up for discussion. The current
direction suggests using links to other docs for things that change
from release to release. For Shared File Systems, we could use links to the
existing devref. The devref is easy for developers to maintain
in-tree. So, that is good for technical details. Unfortunately the
reading experience will suffer if we don't keep "the right amount"
of information in the Configuration Reference. So we'll need to
work on finding that right amount.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Mark Sturdevant (mark-sturdevant)
Other contributors:
Existing vendor docs from manila in-tree devref.
Work Items
----------
* shared-file-systems chapter
* Generated configuration file tables
Dependencies
============
* Manila is near RC1, so functionality is frozen.
* Manila devref documentation for Liberty is not final. Some vendors
should be improving their documentation while this is in progress.
Some pages may need a re-sync once we get a base Config Ref -- or we
could use separate commits for each vendor to try to capture
all their Liberty updates in each first commit.
Testing
=======
Review by the manila core team and contributors.
References
==========
Manila devref:
* http://docs.openstack.org/developer/manila/devref/index.html

120
specs/liberty/reorganise-user-guides.rst
View File

@ -1,120 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=====================================
Reorganize User Guides for Liberty
=====================================
https://blueprints.launchpad.net/openstack-manuals/+spec/reorganise-user-guides
Update the information architecture of the Cloud Administrator Guide,
Admin User Guide, and End User Guide to separate user, administrator,
and operator content, and ensure that the existing content is accurate
and relevant.
Problem description
===================
The current user guides have become disorganized over time, this update
tidies them up.
Proposed change
===============
* Clarify the audience of each guide
* Identify different types of content in the guides
* Reorganize guides to better present existing content
* Clean up existing content where necessary
* Identify information gaps and raise bugs where necessary
* Be sure that terms are well-defined here (or link to other docs
for definitions)
Alternatives
------------
* Leave the guides as they are
* Combine the Cloud Admin Guide and the Admin User Guide
* Combine the Admin User Guide and the End User Guide
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Lana Brindley (loquacity)
Other contributors:
The User Guides specialty team
Anyone with information architecture experience
Work Items
----------
* Develop a user/task matrix and define a limited set of personae to consume
the user guide content.
* Rework the abstract for each guide to clearly identify the audience and
purpose of each book
* Remove the unnecessary/self explanatory procedures from the dashboard
chapter, for example, 'Delete an image' or 'Manage an instance' and so on.
* Determine a good structure for how to present tasks, using the dashboard or
CLI, and editing config files.
* Reduce duplication between the guides as much as possible. Point the Cloud
Admin Guide to the Admin User Guide, and the Admin User Guide to the End
User Guide for readers to accomplish further tasks. This information may
be suited to the Abstracts.
* Update dashboard images for Admin and Project tabs.
* Verify if the procedures are applicable by testing against the Liberty
puddle.
* Consistency with procedures: some have tables, some use variable
list, for example:
* Create Network (normal variable list)
* Launch Instance (variable list in bold)
* Manage stacks and Access & Security (tables)
* Manage objects (bullets)
* Spacing between steps in procedures is inconsistent, for example, check
"Procedure To copy an object from one container to another" and
"Procedure: To create a metadata-only object without a file" in the
"Manage an object" section of User guide.
* Some of the topics are repeated in TOC, for example:
In the User guide, Log in to the dashboard in the OpenStack Dashboard
chapter and from Overview to Manage volumes in the OpenStack command-line
clients chapter. [http://docs.openstack.org/user-guide]
Similarly, some of the sections are repeated in the admin user guide.
[http://docs.openstack.org/user-guide-admin]
Dependencies
============
* None
Testing
=======
* None
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [user guides]
in the subject, weekly user guide `specialty team meeting`_,
weekly `documentation team meeting`_, and potentially etherpads.
.. _`specialty team meeting`: https://wiki.openstack.org/wiki/User_Guides
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

118
specs/liberty/training-labs.rst
View File

@ -1,118 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==============
Training-labs
==============
https://blueprints.launchpad.net/openstack-manuals/+spec/training-labs
OpenStack is made of many projects, with a complex mash of technologies.
Training-labs will provide an automated way of deploying a multi node
OpenStack cluster on a lean basis. Labs scripts should provide an
easy way to setup OpenStack cluster which should be a good starting
point for beginners to learn OpenStack, and for advanced users to
test out new features, check out different capabilities of OpenStack.
On top of that training-labs will also be a good way to test the
install guides on a regular basis and provide automation for those who
would like to focus on installing just one section from install-guides.
Problem description
===================
Deploying OpenStack could be really challenging for beginners. Training-labs
would provide a simple automated way to have a multi-node vanilla OpenStack
deployment on virtual machines. The following are the unique traits:
* Easy to setup and run.
* Minimal dependencies.
* Minimal hardware requirements:
* 4GB RAM
* i3 processor (or similar quad core processor)
* 50GB hard disk space.
* Supports multiple platforms:
* Linux
* Mac
* Windows
* Closely follows and automates install-guides.
* Optionally follow guides under Openrations and Administration Gudies.
* Example: Load Balancer as a Service.
Proposed change
===============
* The work will be carried out by training-labs speciality team.
* Creation of new repository.
* Migrating labs folder under training-guides to the new repository:
* Setup a new github repository for migration.
using git-filter on the labs section of training guides.
* Propose a new repository in OpenStack and import content from
github repository.
* Update training guides repository as required.
Alternatives
------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* dguitarbite
Other contributors:
* rluethi
Work Items
----------
* Migrate labs folder from training-guides to the new repository location:
* Using git-filter get the labs specific content from training-guides
repository.
* Move it to a github repository.
* Create training-labs repository, pull the content from the github
repository.
* Refactor the repository structure to include new architecture.
* Other misc items like IRC notifications, gerrit related configuration.
* Remove labs section from training guides.
* Remove labs related jobs from training guides.
Dependencies
============
* T.B.D.
Testing
=======
* Add bash and python syntax checks.
* Create required infra jobs for training-labs.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [install-guide]
in the subject, weekly Installation Guide `specialty team meeting`_,
weekly `documentation team meeting`_, and potentially etherpads.
.. _`specialty team meeting`: https://wiki.openstack.org/wiki/Documentation/training-labs#Meeting_Information
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

262
specs/mitaka/app-guides-mitaka-vision.rst
View File

@ -1,262 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=============================================
Application Developer Guides - aka API Guides
=============================================
https://blueprints.launchpad.net/openstack-manuals/+spec/app-guides-mitaka-vision
We want to build comprehensive application developer documentation for
public-facing OpenStack REST APIs. These guides aim to empower
consumers to successfully build cloud-native applications. Each
comprehensive guide, delivered on developer.openstack.org, will contain a
collection of conceptual articles, reference information, and how-to
articles.
Problem description
===================
For years, we have published API references. However, application developers
also need conceptual, how-to, and best practice information.
Goals
=====
To better serve this developer.openstack.org audience, we plan to:
- Update the landing and web pages to make developer.openstack.org more usable
- Give application developers information based on their language of choice
- Source information about service capabilities and REST APIs through each
service repository itself
- Ensure that the "First App on OpenStack" is a complete and
easy-to-use first guide
- Automate the generation of API reference information
- Create excellent, helpful, accurate, sufficient app developer guides
- Standardize with the API Working Group doc guidelines in mind
- Organize the guides around developer tasks and workflow rather than around
services
Proposed change
===============
With these general guidelines in mind, let's build a new guide from multiple
sources with this outline:
* Introduction to OpenStack REST APIs
* Build your First App on OpenStack
* Discover OpenStack services, workflows, and resources
* Authenticate as a user
* Inspect the service catalog
* Decide what services and resources you need
* Images
* Manage images
* Compute instances (VMs)
* Understand flavors and images
* Launch an instance
* Provide user data to an instance
* Manage access and security
* Use keypairs
* Use security groups
* Migrate instances
* Networks
* Create networks, ports, routers, subnets
* Load balance across servers
* Block Storage
* Attach volumes with block storage
* Transfer a volume from server-to-server
* Object Storage
* Deploy apps on OpenStack
* Troubleshoot apps on OpenStack
* Libraries and Software Development Kits
* Python
* Go
* .Net
* Java
* nodejs
* Ruby
* PHP
* API Complete References
Based on Swagger, each method should have the following information:
* Method (GET/PUT/POST/PATCH/HEAD/DELETE)
* Resource (identified by the URL)
* Request parameters, type and description including whether it is optional
* Request headers including media-type, content-type, accept, and others
* Response headers (for some APIs)
* Responses including types and description
* Example request headers and body
* Example response headers and body
* Status codes: success and error response codes
* Resource model: data types that can be consumed and produced
These services are scoped for this team's work this release:
* Identity
* Compute
* Images
* Networks
* Block Storage
* Object Storage
* Best practices for apps on OpenStack
How will each section be sourced?
* API Quick Start in the api-site repository
* First App on OpenStack in the api-site repository
* Refresh the landing page in the api-site repository
* api-guide folder in each OpenStack service repository, such as nova
* api-ref info containing migrated Swagger/RST source files
How will consumers find and read these articles? From:
* http://developer.openstack.org
* http://developer.openstack.org/firstapp-libcloud/
* http://developer.openstack.org/api-guide/quick-start/
* http://developer.openstack.org/api-guide/compute/
* http://developer.openstack.org/sdks/ (needs a landing page, currently we use
developer.openstack.org/#sdks, an anchor on the landing page)
* http://developer.openstack.org/sdks/python/openstacksdk/
and so on as we fill out the outline above with content.
What about projects not in this outline?
This outline suggests a pattern for subsequent projects to follow. This
outline creates a framework for application developer docs. We expect trove,
sahara, ironic, and other projects to follow this pattern to best serve their
consumers.
Alternative
-----------
We could continue to produce specifications on specs.openstack.org combined
with API reference information and links to SDKs.
However as the OpenStack ecosystem expands, we want to foster the best
practices for application developers by providing the best experience through
the http://developer.openstack.org.
Implementation
==============
With the completion of both the WADL to Swagger/RST migration
proof-of-concept and the nova repository to developer.openstack.org site
publication proof-of-concept, the following Work items section
describes the remaining implementation tasks.
Assignees
---------
Primary assignee:
russellsim Russell Sim
Other contributors:
* annegentle Anne Gentle
* etowes Everett Toews
* sdague Sean Dague
* kbhawkey Karen Hawkey
* fifieldt Tom Fifield
Work items
----------
* Landing and web pages
* Revise landing page for developer.openstack.org - russellsim
* Create landing page for developer.openstack.org/sdks
- russellsim
* Create web pages for
developer.openstack.org/sdks/python/openstacksdk - etoews
* Content
* Complete First App on OpenStack matrix of SDK support (complete).
Tom should keep communicating about it as he is. - fifieldt
* Ensure that APIs that support micro-versions display that
information - russellsim
* Document the API guides system for teams, including how to write,
where to write, what to write, to use the framework as it is intended -
annegentle
* Remove obsolete content from the SDK landing page. Both the .NET and PHP
projects on the current landing page have been removed due to inactivity,
see https://wiki.openstack.org/wiki/Stackforge_Namespace_Retirement#Inactive_Projects_to_Retire
- annegentle
* Create a new core review team for API documentation specifically including
members of the API working group - annegentle
* Publication jobs
* Write publishing jobs to statically copy Swagger/RST reference
documentation from fairy-slipper to developer.openstack.org
- russellsim, annegentle, and kbhawkey
* Publish the Python SDK OpenStackSDK docs to
developer.openstack.org - etowes
* Communication
* Communicate the January 16th WADL freeze date for cut over to
Swagger/RST - annegentle
* Communicate what teams must do to follow this pattern -
annegentle
* Write a specification for the infrastructure project so that they
understand our need for a server rather than static content for
developer.openstack.org - russellsim
.. note:
* Note, a UX dev from Internap is interested in working on landing pages
after the first pass is complete.
Dependencies
============
* Proof-of-concept complete for fairy-slipper
* Move fairy-slipper into OpenStack Gerrit:
https://review.openstack.org/#/c/245352/
Testing
=======
These deliverables use the tested openstackdocstheme Sphinx theme. No
additional testing resources are expected at this time.
References
==========
* http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html
* http://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html
* https://etherpad.openstack.org/p/nova-v2.1-api-doc
* https://etherpad.openstack.org/p/Mitaka-Docs-API
* http://superuser.openstack.org/articles/openstack-application-developers-share-insights
* http://developer.openstack.org
* http://developer.openstack.org/firstapp-libcloud/
* http://developer.openstack.org/api-guide/quick-start/
* http://developer.openstack.org/api-guide/compute/

111
specs/mitaka/archguide-mitaka-reorg.rst
View File

@ -1,111 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Improve the Architecture Design Guide
==========================================
https://blueprints.launchpad.net/openstack-manuals/+spec/archguide-mitaka-reorg
Reorganize and update the Architecture Design Guide.
Problem description
===================
Currently, the Architecture Design Guide is primarily organised by use case.
However, a combination of features from different use cases is often used when
designing an OpenStack cloud.
It is recommended to reorganise information so the user can consider all the
requirements first, to help determine their OpenStack cloud architecture.
Additional information should be provided when designing an OpenStack
cloud in a development, staged or production environment. The initial proposal
is to reorganise cloud design requirements into chapters, and
consolidate use case examples into a single chapter.
Proposed change
===============
Reorganize and update the guide to improve usability and accessibility of
information. Proposed table of contents:
1. Introduction
2. Identifying stakeholders
3. Functional requirements
4. User requirements
5. Operator requirements
6. Capacity planning and scaling
6.1 Storage
6.2 Networking
6.3 Compute
7. High availability
8. Security requirements
9. Legal requirements
10. Example architectures (reflecting concepts and terminology described in
previous chapters)
Alternatives
------------
- Leave the guide as it is.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* dazzachan
Other contributors:
* Ops Guide specialty team
Work Items
----------
* Reach a consensus on the information architecture
* Rework the abstract to clearly identify the audience and purpose of the book
* Move content to improve information architecture
* Identify information gaps and submit and fix bugs
Dependencies
============
This work is dependent on the guide being converted from DocBook to RST. See
:ref:`archguide-mitaka-rst`.
Testing
=======
Testing will follow the standard documentation review process.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [arch-guide]
in the subject, weekly Ops Guide `specialty team meeting`_,
weekly `documentation team meeting`_, and potentially etherpads.
.. _`specialty team meeting`:
https://wiki.openstack.org/wiki/Documentation/OpsGuide
.. _`documentation team meeting`:
https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
* `Docs swarm etherpad`_
.. _`Docs swarm etherpad`:
https://etherpad.openstack.org/p/openstack-swarm2015
* `Docs swarm specification`_
.. _`Docs swarm specification`:
http://specs.openstack.org/openstack/docs-specs/specs/liberty/arch-guide.html

95
specs/mitaka/archguide-mitaka-rst.rst
View File

@ -1,95 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
.. _archguide-mitaka-rst:
==========================================
Architecture Design Guide: RST conversion
==========================================
https://blueprints.launchpad.net/openstack-manuals/+spec/archguide-mitaka-rst
Convert the Architecture Design Guide from DocBook to RST.
Problem description
===================
The Architecture Design Guide will be converted from DocBook to RST for the
Mitaka release. This conversion is a precursor to reorganising the guide.
Proposed change
===============
Convert the Architecture Design Guide to RST.
Alternatives
------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* shilla-saebi
Other contributors:
* dazzachan
* alexandra-settle
* kato-tomoyuki
* berendt
Work Items
----------
* Ensure bug fix proposals are included in DocBook and RST during the
conversion process.
* Track changes in wiki_.
.. _wiki: https://wiki.openstack.org/wiki/Documentation/Migrate
* Update our build infrastructure so that Sphinx is used for publishing the
Architecture Design Guide.
* Apply the openstackdocstheme template to the guide.
Dependencies
============
The main dependency is on docs.openstack.org infrastructure updates.
Testing
=======
* Test the new HTML design on the following browsers/operating systems:
* Chrome on Ubuntu, Fedora, Mac, Windows
* Firefox on Ubuntu, Fedora, Mac, Windows
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [arch-guide]
in the subject, weekly Ops Guide `specialty team meeting`_,
weekly `documentation team meeting`_, and potentially etherpads.
.. _`specialty team meeting`: https://wiki.openstack.org/wiki/Documentation/OpsGuide
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
* `Migration wiki`_
.. _`Migration wiki`: https://wiki.openstack.org/wiki/Documentation/Migrate

89
specs/mitaka/cli-ref-rst.rst
View File

@ -1,89 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
.. _cli_ref_rst:
================================================
Command-Line Interface Reference: RST conversion
================================================
https://blueprints.launchpad.net/openstack-manuals/+spec/cli-ref-rst
Convert Command-Line Interface Reference from DocBook to ReST.
Problem description
===================
Command-Line Interface Reference uses old DocBook format.
Currently, we use the new docs theme with ReST format.
Proposed change
===============
Convert the Command-Line Interface Reference from DocBook to ReST
including the automation scripts.
Alternatives
------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* kato-tomoyuki
Work Items
----------
* Stop updating the entire guide.
* Modify the output by the command reference generation tool
from DocBook to ReST.
* Convert the manual contents from DocBook to Rest.
* Track changes in wiki_.
.. _wiki: https://wiki.openstack.org/wiki/Documentation/Migrate
* Update our build infrastructure so that Sphinx is used for
publishing the Command-Line Interface Reference.
* Apply the openstackdocstheme template to the guide.
Dependencies
============
The main dependency is on docs.openstack.org infrastructure updates.
Testing
=======
* Test the new HTML design on the following browsers/operating systems:
* Chrome on Ubuntu, Fedora, Mac, Windows
* Firefox on Ubuntu, Fedora, Mac, Windows
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [cli-ref]
in the subject, weekly `documentation team meeting`_, and
potentially etherpads.
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
* `Migration wiki`_
.. _`Migration wiki`: https://wiki.openstack.org/wiki/Documentation/Migrate

91
specs/mitaka/config-ref-common-options.rst
View File

@ -1,91 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=========================================
Config Reference: document common options
=========================================
https://blueprints.launchpad.net/openstack-manuals/+spec/config-ref-common-sections
Problem description
===================
In the configuration reference, configuration options such as database,
AMQP, keystone middleware are poorly documented, or worse, documented
differently in multiple places.
This might be confusing for the reader, and adds maintenance burden.
Proposed change
===============
Common libraries define several configuration options, used by all the
OpenStack projects. Instead of documenting these options for each project,
we could have a specific chapter documenting the configuration options for
common libraries, and refer to this chapter in the projects chapters.
At the moment these options are poorly documented, so this change would also be
a chance to add missing information, or at least provide a better structure to
do so in the future.
This spec only impacts the configuration reference.
Alternatives
------------
* Document everything in all the projects chapters, leading to a lot of
duplication
Implementation
==============
Assignee(s)
-----------
Primary assignee: gpocentek
Work Items
----------
* Generate options tables using ``autohelp`` for the common libraries. The
options would not be removed from the projects tables, to keep providing a
complete set of options for each project.
* Add a new ``Common configuration options`` chapter to the configuration
reference, documenting configuration options available in ``oslo`` and
``keystonemiddleware`` libraries. Documented libraries include
(non-exhaustive list):
* ``oslo.concurrency``
* ``oslo.db``
* ``oslo.log``
* ``oslo.messaging``
* ``keystonemiddleware.auth_token``
* Remove documentation for these options in the projects chapters, if necessary
(AMQP with ``oslo.messaging`` is sometimes documented).
* In each component chapter, add references to the common options sections.
Dependencies
============
None
Testing
=======
* Validate the existence of documented options using the tables generated with
``autohelp``.
References
==========
None

94
specs/mitaka/config-ref-rst.rst
View File

@ -1,94 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
.. _config_ref_mitaka_rst:
=======================================
Configuration Reference: RST conversion
=======================================
https://blueprints.launchpad.net/openstack-manuals/+spec/config-ref-rst
Convert the Configuration Reference from DocBook to RST.
Problem description
===================
The Configuration Reference will be converted from DocBook to RST for the
Mitaka release. The tools generating the configuration options tables will be
modified to generate RST tables instead of docbook tables.
Proposed change
===============
Convert the Configuration Reference to RST.
Update the ``autohelp.py``, ``diff_branches.py`` and ``extract_swift_flags.py``
scripts to generate the configuration options tables.
Alternatives
------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* gpocentek
Work Items
----------
* Update the openstack-doc-tools scripts to support RST output.
* Convert content from DocBook to RST.
* Ensure bug fix proposals are included in DocBook and RST during the
conversion process.
* Track changes in wiki_.
.. _wiki: https://wiki.openstack.org/wiki/Documentation/Migrate
* Update our build infrastructure so that Sphinx is used for publishing the
Configuration Reference.
* Apply the openstackdocstheme template to the guide.
* Import translations from the old guide to the new guide.
Dependencies
============
The main dependency is on docs.openstack.org infrastructure updates.
Testing
=======
* Test the new HTML design on the following browsers/operating systems:
* Chrome on Ubuntu, Fedora, Mac, Windows
* Firefox on Ubuntu, Fedora, Mac, Windows
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [config-ref] in the
subject, weekly `documentation team meeting`_, and potentially etherpads.
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
* `Migration wiki`_
.. _`Migration wiki`: https://wiki.openstack.org/wiki/Documentation/Migrate

72
specs/mitaka/create-manila-install-guide.rst
View File

@ -1,72 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
====================================
Add manila to the installation guide
====================================
https://blueprints.launchpad.net/openstack-manuals/+spec/create-manila-install-guide
Add manila to the installation guide.
Problem description
===================
The installation guide does not include manila, but manila packages are
available in the distros' repositories. Essential documents also
already support manila:
- `Manila admin guide cloud <http://docs.openstack.org/admin-guide-cloud/shared_file_systems.html>`__
- `Manila user guide <http://docs.openstack.org/user-guide/cli_manage_shares.html>`__
- `Manila configuration reference <http://docs.openstack.org/liberty/config-reference/content/ch_configuring-openstack-shared-file-systems.html>`__
Proposed change
===============
Add manila to the installation guide using existing cinder content as a
reference.
Manila architecture is based on cinder architecture. By this means, reference
architecture will be compatible with cinder architecture.
Approach for example/proof-of-concept architecture:
- Shared Filesystems Storage management at the controller node;
- Shared Filesystems Storage service at same the cinder node.
Alternatives
------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
denis-cavalcante
Work Items
----------
None
Dependencies
============
Mitaka milestone or RC packages for each distribution supported by the
Installation Guide.
Testing
=======
Validate manila deployment on all distributions supported by the installation
guide.
References
==========
None

85
specs/mitaka/image-guide-rst.rst
View File

@ -1,85 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
.. _image_guide_rst:
===========================================
Virtual Machine Image Guide: RST conversion
===========================================
https://blueprints.launchpad.net/openstack-manuals/+spec/image-guide-rst
Convert the Virtual Machine Image Guide from DocBook to RST.
Problem description
===================
The Virtual Machine Image Guide will be converted from DocBook to RST
for the Mitaka release.
Proposed change
===============
Convert the Virtual Machine Image Guide to RST.
Alternatives
------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* kato-tomoyuki
Work Items
----------
* Ensure bug fix proposals are included in DocBook and RST during the
conversion process.
* Track changes in wiki_.
.. _wiki: https://wiki.openstack.org/wiki/Documentation/Migrate
* Update our build infrastructure so that Sphinx is used for publishing the
Virtual Machine Image Guide.
* Apply the openstackdocstheme template to the guide.
Dependencies
============
The main dependency is on docs.openstack.org infrastructure updates.
Testing
=======
* Test the new HTML design on the following browsers/operating systems:
* Chrome on Ubuntu, Fedora, Mac, Windows
* Firefox on Ubuntu, Fedora, Mac, Windows
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [image-guide]
in the subject, weekly `documentation team meeting`_, and
potentially etherpads.
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
* `Migration wiki`_
.. _`Migration wiki`: https://wiki.openstack.org/wiki/Documentation/Migrate

84
specs/mitaka/improve-ops-guide.rst
View File

@ -1,84 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Improve the Operations Guide
==========================================
https://blueprints.launchpad.net/openstack-manuals/+spec/improve-ops-guide
Reorganize and update the Operations Guide.
Problem description
===================
The Operations Guide has become outdated over time, with identified gaps in
content.
Proposed change
===============
Based on doc sessions at the Mitaka summit, reorganize and update the guide
to improve usability and accessibility of information.
Alternatives
------------
Leave the guide as it is.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* shilla-saebi
Other contributors:
* Ops Guide specialty team
Work Items
----------
* Reach a consensus on the information architecture
* Rework the abstract to clearly identify the audience and purpose of the book
* Move content to improve information architecture
* Identify information gaps and submit and fix bugs
Dependencies
============
This work is dependent on the guide being converted from DocBook to RST. See
:ref:`ops-guide-rst`.
Testing
=======
Testing will follow the standard documentation review process.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [arch-guide]
in the subject, weekly Ops Guide `specialty team meeting`_,
weekly `documentation team meeting`_, and potentially etherpads.
.. _`specialty team meeting`:
https://wiki.openstack.org/wiki/Documentation/OpsGuide
.. _`documentation team meeting`:
https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
* `Kilo operations midcycle meetup etherpad`_
.. _`Kilo operations midcycle meetup etherpad`:
https://etherpad.openstack.org/p/PAO-ops-ops-guide-fixing

115
specs/mitaka/installguide-mitaka.rst
View File

@ -1,115 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==============================================
Installation Guide: General changes for Mitaka
==============================================
https://blueprints.launchpad.net/openstack-manuals/+spec/installguide-mitaka
Discuss and track general changes to content for existing services in the
Mitaka release.
Problem description
===================
Prior to the Mitaka release, accomplish the following tasks for the
Installation Guide:
* Changes to existing distributions
* Changes to existing OpenStack service or system dependencies
* Addition of new distributions (requires separate spec)
* Addition of new services (requires separate spec)
* Complete testing on all distributions
Proposed change
===============
#. Update content using a combination of the configuration reference and
distribution packages as they become available for Mitaka.
#. Remove defunct Debian content due to persistent lack of maintenance over
many releases.
#. As time and resources permit, implement the following optional
enhancements:
* Replace conventional clients with the ``openstack`` client.
Alternatives
------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
ionosphere80
Other contributors:
berendt
dguitarbite
Work items
----------
Architectural
* None unless OpenStack services dictate it.
Configuration
* Update configuration items using a combination of release notes,
configuration reference, sample configuration files, and gate job
configuration.
Testing
* Perform sufficient `testing`_ on all distributions and track progress.
Dependencies
============
Mitaka milestone or RC packages for each distribution supported by the
Installation Guide.
Testing
=======
* All distributions supported by the Installation Guide must complete
`testing`_ of at least core services (Identity, Image Service, Compute,
and Networking) and successfully launch an instance using both provider
and conventional (tenant/external) network paths prior to release of
Mitaka. Additional services such as Block Storage and Object Storage
also require sufficient testing, but can wait until the documentation
team tags the official stable/mitaka release due to additional resource
requirements. The documentation team may decide to temporarily disable
publication of the installation guide for distributions that do not meet
these criteria.
.. _`testing`: https://wiki.openstack.org/wiki/Documentation/MitakaDocTesting
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [install-guide]
in the subject, weekly Installation Guide `specialty team meeting`_,
and weekly `documentation team meeting`_. Also recommend using the
`etherpad`_ to discuss potential changes before writing patches.
.. _`specialty team meeting`: https://etherpad.openstack.org/p/docinstallteam-agenda
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
.. _`etherpad`: https://etherpad.openstack.org/p/installguide-mitaka

114
specs/mitaka/networkguide-ovn.rst
View File

@ -1,114 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
============================================
Networking Guide: Open Virtual Network (OVN)
============================================
https://blueprints.launchpad.net/openstack-manuals/+spec/networkguide-ovn
Add OVN content to the networking guide in coordination with the development
process.
Problem description
===================
OVN requires sufficient documentation that appeals to potential
deployers when or before it becomes part of an Open vSwitch release
during the Mitaka development cycle or after release.
Proposed change
===============
Develop the following OVN content:
* Introduction including comparison to existing virtual networking
architectures.
* Architecture including components, control plane flow, data plane
flow, etc.
* One or more realistic deployment scenarios including step-by-step
instructions for networking service components.
* Optionally, migration from other architectures such as conventional
Open vSwitch and agents.
All content may contain links to external documentation for general
information rather than duplicating it.
Alternatives
------------
Do not develop OVN documentation that appeals to potential deployers.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
ionosphere80
Other contributors:
emagana
russellb
mestery
Work Items
----------
* Track development and review existing documentation in the following
locations determine a plan for contributions.
http://openvswitch.org/support/dist-docs/ovn-architecture.7.html
http://blog.russellbryant.net/2015/10/22/openstack-security-groups-using-ovn-acls/
https://github.com/openvswitch/ovs/blob/master/tutorial/OVN-Tutorial.md
http://docs.openstack.org/developer/networking-ovn/
* As functions and features become stable, develop architectural content
using a combination of existing and original content.
* As ability to deploy in a traditional multi-node environment becomes
apparent, develop one or more realistic deployment scenarios. All
scenarios require validation using an actual environment before
publication.
Dependencies
============
* Sufficient progress in OVN development.
* Suitable environment for building and validating deployment scenarios.
Testing
=======
* Validate deployment scenarios.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, #openstack-neutron, #openstack-neutron-ovn, the
openstack-docs mailing list, weekly `documentation team meeting`_,
weekly `neutron team meeting`_, weekly OVN meeting on Thursdays
at 13:15 US eastern time in #openvswitch, and potentially
etherpads.
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
.. _`neutron team meeting`: https://wiki.openstack.org/wiki/Network/Meetings

129
specs/mitaka/networkguide-versioning.rst
View File

@ -1,129 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
======================================
Networking Guide: Implement Versioning
======================================
https://blueprints.launchpad.net/openstack-manuals/+spec/networkguide-versioning
Implement versioning of the networking guide including publishing a stable
version for each OpenStack release similar to the installation guide.
Problem description
===================
The networking guide currently uses a continuous deployment mechanism
for publication. In other words, only the master branch resides on
docs.openstack.org. Several releases after initial publication of the
networking guide, the following issues with continuous deployment
became apparent:
* Using wording such as "In Kilo..." or "In Liberty..." is confusing and
often difficult to find if a search leads to a specific page within the
content for a particular feature available in a certain release of
OpenStack. For example, a chapter has a note indicating that the
Liberty release includes a particular feature, but sections within the
chapter lack a note about it.
* Maintaining the deployment scenarios is difficult because features and
configuration options change with each release. For example, DVR in Juno
only supports GRE and VXLAN networks, but DVR in Kilo and newer releases
also supports VLAN networks. Trying to use "In Kilo..." or "In Liberty..."
in configuration snippets makes them increasingly confusing.
Proposed change
===============
Publish stable releases of the networking guide with OpenStack releases.
With the exception of bug fixes, patches apply to the master branch and
require additional consideration for backporting to prior releases.
Stable release tags already exist for the networking guide. However, updates
to the networking guide for a particular release usually occur after that
release. For example, patches for the deployment scenarios in Kilo mostly
merged several months after the Kilo release. Therefore, the existing
stable/kilo tag primarily includes content that applies to Juno and the
stable/liberty tag primarily includes content that applies to Kilo. Aligning
content for prior releases requires careful backporting of a significant
quantity of patches.
After implementation of this specification, updates for a future release
should occur prior to that release similar to the installation guide.
Alternatives
------------
Retain continuous deployment for the networking guide.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
scollins
Other contributors:
jaegerandi
ionosphere80
emagana
Work Items
----------
Phase 1
* Build networking guide for the stable/kilo branch and backport patches
that apply to it.
* Publish the master branch to drafts and Liberty documentation.
* Publish the stable/kilo branch to Kilo documentation.
* Update redirects and index files as necessary.
Phase 2
* Update the networking guide (primarily deployment scenarios) for Liberty
using the master branch.
* Build networking guide for the stable/liberty branch and backport
patches that apply to it.
* Publish the stable/liberty branch to Liberty documentation.
* Update redirects and index files as necessary.
Dependencies
============
None.
Testing
=======
* Verify correct publication prior to moving to the next phase and
ultimately implementing the specification.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, openstack-docs mailing list, weekly
`documentation team meeting`_, bi-weekly
`networking guide sub-team meeting`_, and potentially etherpads.
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
.. _`networking guide sub-team meeting`: https://wiki.openstack.org/wiki/Documentation/NetworkingGuide

98
specs/mitaka/ops-guide-rst.rst
View File

@ -1,98 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
.. _ops-guide-rst:
==========================================
Operations Guide: RST conversion
==========================================
https://blueprints.launchpad.net/openstack-manuals/+spec/ops-guide-rst
Convert the Operations Guide from DocBook to RST.
Problem description
===================
The Operations Guide will be converted from DocBook to RST for the
Mitaka release. This conversion is a precursor to reorganising the guide.
Proposed change
===============
Convert the Operations Guide to RST.
Alternatives
------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* dazzachan
Other contributors:
* shilla-saebi
* alexandra-settle
* kato-tomoyuki
Work Items
----------
* Convert content from DocBook to RST
* Ensure bug fix proposals are included in DocBook and RST during the
conversion process.
* Track changes in wiki_.
.. _wiki: https://wiki.openstack.org/wiki/Documentation/Migrate
* Update our build infrastructure so that Sphinx is used for publishing the
Operations Guide.
* Apply the openstackdocstheme template to the guide.
* Import translations from the old guide to the new guide.
Dependencies
============
The main dependency is on docs.openstack.org infrastructure updates.
Testing
=======
* Test the new HTML design on the following browsers/operating systems:
* Chrome on Ubuntu, Fedora, Mac, Windows
* Firefox on Ubuntu, Fedora, Mac, Windows
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [ops-guide]
in the subject, weekly Ops Guide `specialty team meeting`_,
weekly `documentation team meeting`_, and potentially etherpads.
.. _`specialty team meeting`: https://wiki.openstack.org/wiki/Documentation/OpsGuide
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
* `Migration wiki`_
.. _`Migration wiki`: https://wiki.openstack.org/wiki/Documentation/Migrate

78
specs/mitaka/publish-stable-translation.rst
View File

@ -1,78 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==================================
Publish stable release translation
==================================
https://blueprints.launchpad.net/openstack-manuals/+spec/publish-stable-translation
Add the feature of publication of translated documents for stable release.
Problem description
===================
Currently, Some documents such as Installation Guide have versioned documents.
On the other hand, Translation feature works on master branch only.
So, I18n team can not publish the documents for stable release.
Proposed change
===============
Change translation target from all documents to versioned documents
on stable branch so that translation resources for only versioned
documents are uploaded to Zanata.
Also, execute translation related Jenkins jobs on stable branch.
Translation target are:
* Installation Guide for Liberty
* common-rst
Alternatives
------------
* Don't publish the translation guides for stable release.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* KATO Tomoyuki (to222)
Work Items
----------
* Update the ``doc-tools-check-languages.conf`` file to
change translation resources on stable branch.
* Create branch on Zanata server for repositories.
Dependencies
============
The main dependency is on docs.openstack.org infrastructure updates.
Testing
=======
Testing will follow the standard documentation and translation
review processes.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-i18n, the openstack-i18n mailing list,
`I18n team meeting`_, and `Mitaka Design Summit Etherpad`_.
.. _`I18n team meeting`:
https://wiki.openstack.org/wiki/Meetings/I18nTeamMeeting
.. _`Mitaka Design Summit Etherpad`:
https://etherpad.openstack.org/p/tokyo-i18n-meetup

148
specs/mitaka/review-docimpact.rst
View File

@ -1,148 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
================
Review DocImpact
================
https://blueprints.launchpad.net/openstack-manuals/+spec/review-docimpact
The ``DocImpact`` script creates a lot of noise on the openstack-manuals bug
list. This is partly a social problem (we need to train contributors to use
the ``DocImpact`` flag more thoughtfully), but also partly an automation
problem (we should be considering how the ``DocImpact`` flag is used, and the
most efficient automation to achieve the end we require.
Problem description
===================
Current workflow: Contributors create a patch, and at commit time they think
"oh yeah, probably there should be some docs about that" and whack in a
``DocImpact`` flag. In other words, there's not a lot of thought going in
here, it's just an easy thing to do, they get a warm fuzzy, and there's an
assumption that the documentation fairy comes along and takes care of things.
In reality, what then happens is some docs triager spends an hour looking at
the patch, searching through the docs, then deciding it has nothing to do with
openstack-manuals. Often, the actual doc impact (if there even is one) is
against docs in the dev repo, not openstack-manuals.
In short, contributors recognise they need docs, and ``DocImpact`` is an easy
way to feel like they're doing something productive to make that happen. What
really happens is that those bugs are largely irrelevant for
openstack-manuals, which puts pressure on our core team to triage them
effectively. To try and get some perspective on the size of the problem, here
are some numbers:
Of the 508 current openstack-manuals bugs, 214 are the result of the DocImpact
script. 51 of these are yet to be triaged. Right now, there are 170 patches
in-flight with the DocImpact tag. To state the obvious, if all them land,
that's 170 new bugs in our queue.
Proposed change
===============
* Adjust ``DocImpact`` so that it cannot be used without a description.
Currently, that is an optional thing contributors can do, but it appears
that no one uses it. This would mean that rather than typing "DocImpact" and
moving on with their lives, contributors must write "DocImpact: Something
relevant here".
* A Jenkins job is used to test for the description field in patches. If no
description field is found, the Jenkins job will fail.
* Currently, all projects default to create a bug in the openstack-manuals
queue. This behaviour will be changed so that all projects default
to raising a bug in their own repo, and only the five defcore projects
(Nova, Swift, Glance, Keystone, and Cinder) go to the openstack-manuals
queue. (Neutron to be added once it becomes defcore, planned for 2016).
* Create an education campaign on the dev mailing list, and possibly other
channels, in order to try and encourage contributors to use the flag
responsibly.
Examples
--------
Some examples of correct ``DocImpact`` usage:
* Where the documentation needs to be updated:
.. code-block:: ini
DocImpact: Update in the Networking section of the Ubuntu Install Guide
* The type of documentation required:
.. code-block:: ini
DocImpact: Add a description and install info for $NEW_FEATURE.
* Changes to existing documentation:
.. code-block:: ini
DocImpact: Current docs say X, should be Y.
* Link to a longer piece of documentation (such as OpenStack pastebin,
etherpad, or a blog post):
.. code-block:: ini
DocImpact: For more info, see http://paste.openstack.org/show/479079/
Alternatives
------------
* Have a crack team of docs people (potentially with automation
assistance) going through ``DocImpact`` bugs, cc'ing the original patch
authors, triaging the valid ones, moving others into dev repos where
necessary, and marking the rest invalid. We could team this with an
education campaign on the dev mailing list.
* Ditch ``DocImpact``, and force contributors to create their own docs bugs
(and patches). This would mean fewer contributors get on with the job of
documentation, but at least what we do get would be well-considered, rather
than hastily added to their commit message.
* ``DocImpact`` doesn't log a bug at all but rather indicates that the patch
contains docs. This style of commit message then aligns with APIImpact,
where the API Working Group reviews incoming patches with that tag. This
won't work currently, as we don't have a good mechanism for searching for
the flag (the current docs dashboard doesn't do this).
* Do nothing. Leave the ``DocImpact`` flag the way it is, and slowly drown.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* Lana Brindley (loquacities)
Other contributors:
* Documentation team
* Infra team
Work Items
----------
* Enforce a description field on the DocImpact flag. (Infra)
* Review the projects that can raise DocImpact flags in the openstack-manuals
queue. (AJaeger)
* Plan and implement an education campaign. (loquacities)
References
==========
* https://lists.launchpad.net/openstack-doc-core/msg00286.html

110
specs/mitaka/trove-install-section.rst
View File

@ -1,110 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
====================================
Add trove to the installation guide
====================================
https://blueprints.launchpad.net/openstack-manuals/+spec/create-trove-install-guide
Add trove to the installation guide.
Problem description
===================
The installation guide does not include trove, but trove packages are
available in the distros' repositories. Essential documents also
already support trove:
- `trove admin guide cloud <http://docs.openstack.org/admin-guide-cloud/database.html>`__
- `trove user guide cmd line <http://docs.openstack.org/user-guide/trove-manage-db.html>`__
- `trove user guide dashboard <http://docs.openstack.org/user-guide/dashboard_databases.html>`__
- `trove configuration reference <http://docs.openstack.org/liberty/config-reference/content/ch_configuring-trove.html>`__
- `trove API reference <http://developer.openstack.org/api-ref-database-v1.html>`__
Proposed change
===============
Add the following trove content to the installation guide:
**Prerequisites:**
Working OpenStack environment with at least Compute, Image Service, Identity.
- Backup and restore, add Object Storage.
- Provision datastores on block-storage volumes, add Block Storage.
**Installation:**
Install required packages.
Source ``admin-openrc.sh`` and create trove user.
Set OpenStack service URLs and RabbitMQ
values in ``trove.conf``,
``trove-taskmanager.conf``,
and ``trove-conductor.conf``.
Set correct ``api-paste.ini`` file values for ``auth_uri``,
``identity_uri``, ``admin_user``, ``admin_password``,
``admin_tenant_name``, ``signing_dir``.
Edit ``trove.conf`` for default datastore, network label, regex,
and API information.
Edit ``trove-taskmanager.conf`` to connect to the OpenStack Compute service.
Prepare the trove admin database.
Initialize database and create datastore.
Create a trove image.
Update the datastore to use the new image.
Register trove with keystone.
To deal with Ubuntu package bug - change the service startup scripts to use
the correct conf files.
Start or restart (depending on env) trove services.
Alternatives
------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Laurel Michaels
Work Items
----------
None
Dependencies
============
Mitaka milestone or RC packages for each distribution supported by the
Installation Guide.
Testing
=======
Validate trove deployment on all distributions supported by the installation
guide.
References
==========
None

107
specs/mitaka/ui-content-guidelines.rst
View File

@ -1,107 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==============================================
Add UI content guidelines to Contributor Guide
==============================================
https://blueprints.launchpad.net/openstack-manuals/+spec/ui-content-guidelines
Add a new section describing UI content guidelines within the OpenStack
Documentation Contributor Guide.
Problem description
===================
The OpenStack UX project is interested in adding a section to the
OpenStack Documentation Contributor Guide that provides guidance
on maintaining consistent structure, style, and syntax for any
graphical user interfaces (GUI) developed by the OpenStack project teams.
The guide could be applied to IA efforts for the panel headings,
modal headings, modal section headings, section descriptions, labels, etc.
The value of this effort is to help provide an improved
usability for operators, admins and end users.
Proposed change
===============
Add a section to address UI content guidelines.
This UI content guidelines section could be
added as a peer to the Writing Style section within the
OpenStack Documentation Contributor Guide.
Proposed table of contents:
* Value/Intro
* Capitalization guidelines for text in UI
* Examples of sentence-style capitalization
* Examples of headline-style capitalization
* Common UI elements/headings that use sentence-style capitalization
* Common UI elements/headings that use headline-style capitalization
* UA Cheat Sheet (visually show style in an image)
* Common action labels (i.e. Cancel, Add, Close, Delete, etc...), other
common labels (i.e. IP address)
* Refer to user interface elements consistently (link to ui-terminology.html)
* Follow writing style guidelines (link to page in contributor guide)
* Error message guidelines (structure, clarity, completeness)
* Structure definitions
* Examples
Alternatives
------------
- Do not add UI content guidelines.
- Add guidelines, but create a new guide.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* pkruithofjr@gmail.com
* stemke@us.ibm.com
Other contributors:
* gmolson@us.ibm.com
* nancy.ann.michell@hpe.com
* openstack@lanabrindley.com
Work Items
----------
* Reach a consensus on new section's location and content structure.
* Identify new topics to be created and submit content/reviews using the
[blueprint ui-content-guidelines] tag.
Dependencies
============
This work is a collaboration between the UX and Doc team that requires
input from both projects.
Testing
=======
Testing will follow the standard documentation review process.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with
[ui-content-guidelines] in the subject.
.. _`documentation team meeting`:
https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

96
specs/mitaka/upgrades.rst
View File

@ -1,96 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
========
Upgrades
========
https://blueprints.launchpad.net/openstack-manuals/+spec/upgrades
Improve upgrade content by replacing rigid step-by-step procedures that
involve the installation guide architecture and upstream distribution
packages with more general procedures that appeal to a wider audience.
Problem description
===================
The existing upgrade content in the Operations Guide includes rigid
step-by-step procedures that rely on the simple installation guide
architecture and upstream distribution packages. Our audience of
operators deploy OpenStack in a variety of ways and would benefit
from more generic procedures that apply more easily to different
environments.
Proposed change
===============
Develop the following content for each service:
* Outline of the typical process including common issues. For example, address
mandatory operational or configuration changes, stop the service, upgrade
the code, upgrade the database schema, start the service, verify operation
of the service.
* Mandatory or significant operational or configuration changes between
releases.
* Links to release notes and configuration reference for other changes.
Mandatory or significant operational or configuration changes between
releases only consider upgrades from N-1 to N release back to the most
recent EOL release. Given time constraints, development prioritizes
upgrades between more recent releases.
Alternatives
------------
Continue using the existing content, likely without updates for recent
releases.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
none
Other contributors:
none
Work Items
----------
* Develop a generic upgrade procedure.
* Determine mandatory or significant operational or configuration changes
between releases and test upgrades using these changes.
Dependencies
============
* Suitable environment for deploying various releases and performing
upgrades.
Testing
=======
* Verify generic upgrade procedure and augmentation with mandatory or
significant operational or configuration changes for each release.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list, weekly
`documentation team meeting`_, and potentially etherpads.
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

353
specs/mitaka/user-guides-mitaka-reorg.rst
View File

@ -1,353 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
User Guides Reorganization for Mitaka
==========================================
Edit Cloud Administrator Guide, Admin User Guide, and the End User Guide
to ensure the content supports administrators, end users, and cloud
administrators.
Problem description
===================
Having converted these guides to RST during the Liberty cycle, we can now
reorganize their content to improve consistency and reduce duplicated content.
Assess relevance and accuracy of the current content and improve links between
guides for similar tasks and concepts.
Proposed change
===============
1. Edit content for stylistic inconsistency and content accuracy:
* Clean up existing content with grammar checks, use of definite articles,
and verb subject agreement.
* Address consistency of tables across the guides - adjust to a
variable list with bold headings, or a table with :code-block: roles
inside cells to highlight commands.
* Reorganize troubleshooting sections into a single format - change the
Troubleshooting sections to use a "Problem" and "Solution" format
used in the Block Storage Chapter.
2. Clarify the audience of each guide using a user task matrix and results
from the OpenStack foundation administrator survey. Reorganize content
appropriately.
3. Restructure the guides by merging content from the Administrator User
Guide into the Cloud Administrator Guide. Remove the
Administrator User Guide from openstack-manuals.
4. Rename the Cloud Administrator guide after merging content. Change
the document title to Administrator Guide.
5. Remove the Python SDK source files from openstack-manuals, move the
files to the api-site, and publish to developer.openstack.org. The
current published files are at http://docs.openstack.org/user-guide/sdk/html
and the source is at
http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/user-guide/source/sdk*.rst
Alternatives
------------
1. Implement only the first and second proposed changes, keeping three separate
guides.
2. Implement only the first proposed change, editing the content as described.
3. Make no changes, and leave the guides as they are.
Implementation
==============
Assignee(s)
-----------
Joseph Robinson(joseph-r-email)
Brian Moss(kallimachos)
Other Contributors
------------------
The User Guide Team, and anyone willing to test procedures for accuracy or
proofread the guides.
Contact team leads not currently listed in the guides for
discussion on what tasks and actions are most useful and
needed for an Administrator Guide, and confirm
glossary items: Designate, CloudKitty, Magnum, and Zaqar.
Work Items
----------
Work items are broken down by chapters from the Cloud Admin Guide.
Identity Management
~~~~~~~~~~~~~~~~~~~
* User CRUD: include information and a brief procedure on how
to do this in the ADMIN USER Guide.
* Start the identity Service: Move this content into another section
to reduce the number of files in the repository.
* External authentication with Identity: Another smaller section in the
identity service that can merge.
Dashboard
~~~~~~~~~
* Check Liberty Dashboard updates and changes.
Compute
~~~~~~~
* AMPQ: introductory colons to introduce a list. Capitalize
abbreviations in brackets - change (ampq) to (AMPQ).
* Hypervisors: Reorganize and link to the Admin User Guide. Include a
section on how to use a hypervisor.
* Tenants, users, roles: remove passive voice. Link to the
"How Can I Use The Cloud?" section of the End User Guide
*Admin User Guide* - Create and manage roles - reorganize this content to
align with the Cloud Admin Guide content.
EC2 compatibility
~~~~~~~~~~~~~~~~~
* Remove passive voice.
* Compare this section with the liberty installation guide.
Building Blocks
~~~~~~~~~~~~~~~
* Introduction: Clarify what base operating system is referred to here.
Check content for accuracy.
* The nova image-list command. Link together the content on the nova
command line client with the *End User Guide* here.
Images and Instances
~~~~~~~~~~~~~~~~~~~~
* Align the introduction with the *End User Guide*.
* Align the Launching instances and the Adding and removing resources
section with the *Admin User Guide*.
* "This diagram shows the system state prior to launching an instances"
Describe the parts of the diagram. The paragraph is not clear. Extend to
the modifications to the other diagrams.
Networking with nova-network
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Improving troubleshooting sections, as identified by recent research
into user `nova-network to neutron adoption and migration`_.
* The Cloud Admin Guide references floating IP addresses, which users can
change. The User Guide section on Networking will need reorganization to
line up with this content. Information on how to assign IP addresses to VM's
also needs testing.
* VLAN Network Manager: Check paragraph indentation.
* nova network-create vmnet: Address table consistency across guides.
* Configure Compute to use IPv6 addresses: Address table consistency
across guides.
Metadata
~~~~~~~~
* Liberty to Mitaka-metadata services now include 'project_id' according to
release notes.
* Metadata needs an SME check for currency. (Andrew Bogott, John Garbutt,
Matthiew Gagne)
* Description of metadata config options table: Address table consistency
across guides.
Flavors
~~~~~~~
* Flavors define these elements table: Address tables consistency
across guides. (Bold headings with sentences here).
* Are the tables in the *Admin User Guide* on setting flavors effective?
* Show Host Usage Statistics: Host usage statistics description, and
change to bold headings.
Secure with Rootwrap
~~~~~~~~~~~~~~~~~~~~
* Configuration option [Default]: SME to check, and change to better format.
Might need a code snippet
* Migrate Instances: These tables were code snippets. Can they be
replaced with images or appropriate code snippets?
* VNC configurations options: Include a descriptions of VNC configuration
options
* Frequently Asked Questions: An FAQ in the guide clashes with the other
information.
* Information Architecture checkup needed here to rework this information.
* Security Hardening: Improve the OpenStack with Trusted Compute Pools
Second diagram. a new diagram needs headings, and consistency with
the other diagrams.
* Recover Cloud After disaster: Test or have SME check on this procedure.
Object Storage
~~~~~~~~~~~~~~
* *User Guide*: The Create and manage object containers section needs content
from the introduction to the Object Storage section of the
*Cloud Admin*. "...Object Storage (code-named swift is open source
software for creating redundant, scalable data storage using clusters..."
* Object Storage Characteristics - Does not mention containers, but the *User
Guide* mentions this term. Edit for Consistency.
* Components: Edit passive voice usage, and adjust the opening sentence
introducing the components. Move the descriptive opening sentence to
the introduction, and into the *Admin User Guide* section on Object Storage.
* Rings: Underneath the Ring diagram, edit these sentences for a comma splice.
* Zones: Mentions the high availability plus other components already mentioned
in the Components section. So, Components description is not needed. Edit for
repetition.
* Partitions: Edit for punctuation - Comma Splice
* Change the Cluster Architecture and Ring Builder Sections within the Block
storage chapter.
* Account Reaper: "In the background, the account reaper removes
data from deleted accounts..." Edit the syntax here.
* Object Storage Monitoring - Excerpt from a blog. Keep or remove? This
section also needs a syntax review.
Block Storage
~~~~~~~~~~~~~
* Block Storage: persistent storage needs to be mentioned earlier and more
clearly in this introduction.
* Migrate volumes: These commands could appear in the *End User Guide*
* Block Storage command line list: "cinder-manager host lists",
"cinder get-pools" Adapt for the *Admin User Guide*.
* Back up and Restore volumes: Is this procedure a cloud admin procedure, or
can the basic information be adapted to the *Admin User Guide*? Requires role
clarification.
* Clarify if the Transfer a volume section in the *Admin User Guide* is
similar to the Export and import backup metadata procedure in the
*Cloud Admin Guide*.
* Configure and use volume number weigher: This procedure references cinder
commands described in the *End User guide* and *Cloud Admin Guides*.
Reorganize this content.
* Supported Operations in filter and goodness
functions: Remove passive voice in the
Caution note.
* Rate-limit volume copy Bandwidth: Reorganize the guide such that
this content appears closer to the information on moving and
migrating block storage volumes
("volume_copy_bps_limit").
* Image volume cache: Remove passive voice.
* Get capabilities: This section describes actions an administrator
can take with an API,
capability investigation. Reorganize this information with the
*Admin User Guide*.
* Multipath call failed exit: This Troubleshooting section
recruits a Problem and Solution heading architecture useful
for the other Troubleshooting sections of the
Cloud Admin Guide.
Shared File System
~~~~~~~~~~~~~~~~~~
* Key Concepts: Remove passive voice.
* Share basic operations: " General concepts " edit or clarify this phrase.
* Manila commands show, update, and delete options could appear in the
*Admin User Guide*. Clarify Shared File System responsibilities.
* Manage and unmanage share: Edit missing words in some sentences
* Resize a share: Also missing words here.
* Quotas and Limits: Edit verb subject agreement.
* Share snapshots: Include the manila snapshot-create command listed in
the *Admin User Guide* here.
* Consistency group: Edit verb subject agreements ("admin to admins").
* Scheduling: Edit for article and definite articles.
* Networking - Edit for missing words.
* Share networks - Edit verb subject agreements
Networking
~~~~~~~~~~
* Plug-in configurations section: Document the most common ml2 plug-in
configurations.
* Reference network option plugins for ml2
http://docs.openstack.org/liberty/config-reference/
content/networking-options-plugins-ml2.html.
See https://bugs.launchpad.net/openstack-manuals/+bug/1411624
* Use Networking section: Networking Tables need consistency with the
other *Cloud Admin Guide* tables.
* Networking Architecture: This section's description of architecture
would be better placed following the introduction.
* Configuring Identity for Networking: A note about not using Nova-network
with compute appears here,
but needs to appear earlier - the introduction - as a warning for cloud
administrators.
Database
~~~~~~~~
* No recommended changes currently.
Baremetal
~~~~~~~~~
* No recommended changes currently.
Orchestration
~~~~~~~~~~~~~
* No recommended changes currently.
Telemetry
~~~~~~~~~
* Data Retrieval: The code snippet tables need to fit the page.
* Measurements: Confirm that no other measurement items are added
from the Liberty release.
Orchestration
~~~~~~~~~~~~~
* Orchestration Authorization Model: This section requires an edit for grammar.
* Stack domain users: Grammar Edits also required for this section.
* Cross-origin resource sharing: The sub-section "enabling CORS with
configuration" needs an edit to change into a procedure
rather than a list of items.
Cross-project features
~~~~~~~~~~~~~~~~~~~~~~
* No recommended changes currently
Redirects and Build Jobs
~~~~~~~~~~~~~~~~~~~~~~~~
* File redirects and performing build jobs as needed is also
required.
Project Scope
=============
* OpenStack's project navigator describes project maturity. Statistics
listed on the `Project Navigator`_ page cover the project Age,
adoption percentage, stable branch presence, corporate diversity,
SDK support, and install guide content.
* OpenStack projects with longevity, that comply with several of these
statistics, include Nova, Neutron, Swift, Cinder, Keystone, Glance,
Horizon, and Heat. The scope of this reorganization will improve content
on these services accross the guide, but without large scale changes.
* More recently developed project still seeking more maturity indicators,
that may also be 3 or less years into their development, include
*Zaqar*, *Murano*, *Sahara*, and *Trove*. *Manila* content requires
attention, which is described in the Shared File System section
under the Work Items heading. The scope of this reorganization
extends to including content from these more recent projects.
Introducing or improving new content from more recent projects is
a large scale change for this reorganization.
Dependencies
============
* None
Testing
=======
* Some testing required for networking, and core services on Devstack
environments, and OpenStack test installations.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [user guides]
in the subject, weekly user guide `specialty team meeting`_,
weekly `documentation team meeting`_, and notes for any further work
items can be recorded in the `User Guide Etherpad`_.
.. _`specialty team meeting`: https://wiki.openstack.org/wiki/User_Guides
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
.. _`User Guide Etherpad`: https://etherpad.openstack.org/p/UserGuideSpecification
.. _`Project Navigator`: http://www.openstack.org/software/project-navigator
.. _`nova-network to neutron adoption and migration`: https://wiki.openstack.org/wiki/HorizonUsability_Testing#Results_Presentation

79
specs/mitaka/zaqar-config-ref.rst
View File

@ -1,79 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
========================================================
Add Messaging Service(zaqar) to the Config Reference
========================================================
Launchpad blueprint:
https://blueprints.launchpad.net/openstack-manuals/+spec/zaqar-config-ref
Messaging service(zaqar) should be added to the Config Ref similar to
the other OpenStack services.
Problem description
===================
Messaging service(zaqar) is not currently included in the
Configuration Reference. The related content is currently kept in-tree
in the zaqar devref. Administrators using messaging service would expect to
find a reference document from the official Configuration Reference. The
automated configuration doc tools should be leveraged.
Proposed change
===============
The content would be similar to the other services in that it would have
sections to describe introduction, backends, log files, and options.
Automatically generated configuration tables should be used where possible.
Alternatives
------------
N/A
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Fei Long Wang (flwang)
Other contributors:
Existing docs from zaqar in-tree devref.
Work Items
----------
* Messaging service chapter
* Generated configuration file tables
Dependencies
============
Now the conversation to RST is ongoing, so it would be better to get this in
once that's done.
Testing
=======
Review by the Zaqar core team and contributors.
References
==========
Zaqar devref:
* http://docs.openstack.org/developer/zaqar/index.html

180
specs/newton/arch-guide-restructure.rst
View File

@ -1,180 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=====================================
Architecture Design Guide Restructure
=====================================
Problem description
===================
Currently, the Architecture Design Guide is primarily organised by use case.
However, a combination of features from different use cases is often used when
designing an OpenStack cloud.
It is recommended to reorganise information so the user can consider all the
requirements, to help determine their OpenStack cloud architecture.
Additional information should be provided when designing an OpenStack cloud
in a development, staged or production environment. The proposal is to develop
a more detailed structure that creates an abstraction between cloud
architecture concepts and various OpenStack projects. This will make it
easier to maintain and update the guide.
Proposed change
===============
The proposed structure of the guide is to first describe common cloud use
cases, then general architectural concepts, followed by a Design chapter
with a detailed breakdown of the major cloud architecture components.
The section headings in the Design chapter would be as follows:
#. Technical Detail
#. Capacity and Scale
#. High Availability
#. Operator Requirements
#. Deployment Considerations
#. Maintenance Considerations
The headings are intended as a guideline to the type of information that should
be provided. It will be used only when there is a specific need to call out
the information.
Proposed Table of Contents
--------------------------
The new proposed structure for the Architecture Design Guide is as follows:
#. General Overview
#. Use Cases
#. Development Cloud
#. Stakeholder
#. User Stories
#. Design Model
#. Component Block Diagram
#. General Compute Cloud
#. Stakeholders
#. User Stories
#. Design Model
#. Component Block Diagram
#. Web Scale Cloud
#. Stakeholders
#. User Stories
#. Design Model
#. Component Block Diagram
#. Public Cloud
#. Stakeholders
#. User Stories
#. Design Model
#. Component Block Diagram
#. High Availability
#. Overview
#. Capacity and Scale
#. Overview
#. Design
#. Compute
*All topics related to the implementation of the compute platform,
i.e. hypervisors, nova, ironic, etc.*
#. Storage
*All topics related to storage choices and the implementation of
projects like cinder, manila, etc.*
#. Networking
*All topics related to networking design choices such as SDN, LBaaS
and neutron.*
#. Identity
*Topics about authentication, authorisation and assignment at
all levels for keystone and any other related projects.*
#. Image
*Topics about the management, creation, distribution and
deployment of images for glance and other related projects.*
#. Control Plane
*Topics discussing the general implementation of the OpenStack
control components and the decision making that goes into the
choices that need to be made.*
#. Dashboard and APIs
*Topics about the interaction with cloud services using
a graphical interface or the OpenStack APIs. This would
include horizon and other Cloud Management Platform (CMP) tools.*
Alternatives
------------
Leave the guide as is
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* shilla-saebi
Other contributors:
* dazzachan
* shaunom
Work Items
----------
* Reach a consensus on the information architecture
* Rework the abstract to clearly identify the audience and purpose
of the book
* Move content to improve information architecture
* Identify information gaps and submit and fix bugs
Dependencies
============
None
Testing
=======
Testing will follow the standard documentation review process.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [arch-guide]
in the subject, biweekly Ops Guide specialty team meeting,
weekly documentation team meeting, and potentially etherpads.
.. _`Ops/arch tasks etherpad`: https://etherpad.openstack.org/p/ops-arch-tasks

108
specs/newton/consistency-file-rename.rst
View File

@ -1,108 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==============================================
Consistent file naming for search optimization
==============================================
Problem description
===================
Now that the migration to RST has settled down, we can see that using the
former xml:id for file names meant that some RST file names use underbar (_) as
space indicators and some RST file names use hyphen (-) as space indicators.
Our conventions are to use hyphens for all RST files so that the resulting
built HTML files are human-readable and search-engine-readable.
Proposed change
===============
Update all files in the openstack-manuals repository, a guide at a time, to
match our convention of using hyphens for RST file names.
Change any RST file names using underscore to use hyphen instead. Do not change
file names if they use hyphens for spacing.
Change any folder names using underscore if and only if the folder results in
output on a URL that contains an underscore.
Do not change image or figure file names.
Change any hyperlinks that refer to underscore-named files.
Redirect any old file names to new file names on the web server itself in the
``www/static/.htaccess`` file.
Alternatives
------------
Keep the file names as-is and change our convention to use either hyphens or
underscores. This results in decreased findability for files on the site.
Implementation
==============
Assignee(s)
-----------
* admin-guide: Anne Gentle
* cli-reference: Kato Tomoyuki
* config-reference: Kato Tomoyuki
* common: Akihiro Motoki
* user-guide: Mariia Zlatkova
* ops-guide: Olena Logvinova
* backporting link fixes: Akihiro Motoki
Work Items
----------
Change file names and links in:
* admin-guide
* cli-reference (glance_property_keys.rst is the only file)
* common
* config-reference
* ops-guide
* user-guide
These guides have no need to change file names:
* arch-design
* config-reference
* contributor-guide
* ha-guide
* image-guide
* install-guide
* install-guide-debconf
Change links in stable/mitaka and stable/liberty branches that go to changed
file names due to changes in non-versioned deliverables by backporting link
changes.
Update the sitemap.xml file to ensure all new file names are in the sitemap.
Dependencies
============
Coordination of efforts and landing patches.
Testing
=======
Test changed file names for no broken links resulting.
Test redirects.
References
==========
Contributor guide: http://docs.openstack.org/contributor-guide/docs-structure.html#file-naming-conventions
To get the list of Work Items I ran this type of search::
ls ~/src/openstack-manuals/doc/user-guide/source/ | grep _

79
specs/newton/contributor-guide-release-chapter.rst
View File

@ -1,79 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
========================================
Add release chapter to Contributor Guide
========================================
https://blueprints.launchpad.net/openstack-manuals/+spec/release-chapter-contrib-guide
Information about how to conduct a documentation release is currently
contained in a wiki page, an etherpad, and several peoples' heads. In order
to make this content more accessible, to allow more people to be involved
in documentation releases, and to create a pipeline of people who understand
how to do a release, this should be documented in the Contributor Guide.
Problem description
===================
Current information about release procedures for documentation is contained
in a wiki page, several etherpads (see References), and other knowledge
is shared between a small number of people who have hands-on experience
with releases. This could potentially lead to data loss if the wiki is
decommissioned, or if etherpad has an outage. It also can lead to problems
if any of the subject matter experts are not available for consultation
during the release period.
Proposed change
===============
Add a new chapter to the Contributors Guide to consolidate the information
from the wiki, the etherpad, and the institutional knowledge.
Alternatives
------------
Do nothing: keep the information in its current locations, and hope no one
gets hit by a bus.
Implementation
==============
Assignee(s)
-----------
* Lana Brindley (Docs PTL)
* Andreas Jaeger (Docs Infra)
* Anne Gentle (Past Docs PTL)
* Past and present release managers
Work Items
----------
* Create new chapter in Contributor Guide (Lana)
* Add information from the wiki to the new chapter
* Add information from the past etherpad to the new chapter
* Add information from the current etherpad to the new chapter
* Have SMEs review and update content
* Review chapter after each release
Dependencies
============
None.
Testing
=======
None.
References
==========
* http://docs.openstack.org/contributor-guide/
* https://wiki.openstack.org/wiki/Documentation/Release
* https://etherpad.openstack.org/p/MitakaRelease
* https://etherpad.openstack.org/p/NewtonRelease

74
specs/newton/contributor-guide-reorg.rst
View File

@ -1,74 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==============================================
Documentation Contributor Guide reorganization
==============================================
https://blueprints.launchpad.net/openstack-manuals/+spec/contributor-guide-reorg
To facilitate more documentation contributions,
we should keep the contributor guide as readable as possible.
Problem description
===================
The Documentation Contributor Guide contains various useful contents
for the docs contributors. Since we have added content gradually,
however, the guide has become scattered.
Proposed change
===============
1. Sort current contents by task group.
2. Clarify the tasks to contribute docs.
3. Reorganize and add the contents by tasks.
Alternatives
------------
Keep the current guide as is.
Implementation
==============
Assignee(s)
-----------
* Olga Gusarenko
* KATO Tomoyuki
Work Items
----------
* Sort current contents by task group.
* Clarify the tasks to contribute docs.
* Reorganize and add the contents by tasks.
* Refine the contents for first timers.
* Refine the contents for docs readers, such as bug reporting.
* Refine the contents to build docs.
* Refine the contents to write docs.
* Refine the contents to review docs.
* Refine the contents to contribute API docs.
* Refine the contents to contribute installation guides.
* Refine the contents to contribute UI/UX docs.
* Refine the contents about team.
Dependencies
============
None.
Testing
=======
None.
References
==========
* http://docs.openstack.org/contributor-guide/
* https://etherpad.openstack.org/p/austin-docs-contributorguide

94
specs/newton/docbook-removal.rst
View File

@ -1,94 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==============================
Removal of DocBook XML Support
==============================
https://blueprints.launchpad.net/openstack-manuals/+spec/docbook-removal
With the last conversions to RST done for the Newton cycle, we can
simplify our tools to only handle RST and thus remove DocBook XML support.
Problem description
===================
The tools support DocBook XML which is not needed for Newton deliverables.
Right now the tools are used to build and publish DocBook XML for:
* The ``trove`` repository.
* The ``api-site`` repository.
* The ``openstack-manuals`` repository on kilo and liberty stable
branches.
* The ``operations-guide`` repository.
The operations-guide repository has one guide that is nearly finished
with RST conversion. The api-site repository contains the API
reference which is currently converted to RST. The trove repository
work has not started.
Additionally, the ``clouddocs-maven-plugin`` is used to publish
DocBook XML manuals. It is used also in heat, senlin, and zaqar
repositories for documents that are not published at all.
Proposed change
===============
Simplify all tools to only handle RST, remove support for DocBook XML.
Freeze the clouddocs-maven-plugin, we will not do any new features for
it and retire the repository as soon as projects are not using it
anymore for publishing of documents.
Alternatives
------------
* Keep status quo.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
jaegerandi (Andreas Jaeger)
Work Items
----------
* Discuss with trove team the removal.
* Inform heat, senlin, zaqar teams about removal.
* For repositories that need XML publishing: Pin the
openstack-doc-tools version to 0.34 since that is the last release
with XML support.
* Convert glossary to RST and remove XML publishing from
openstack-manuals repository.
* Remove DocBook XML publishing from openstack-doc-tools.
* Remove DocBook translation handling from openstack-doc-tools.
* Update contributor guide for this change.
* Update documentation in openstack-doc-tools for this change.
Dependencies
============
* Publishing of RST version of OPS guide.
Testing
=======
* Testing of the tools will be done manually and as part of the
builds. We should add some method to do integration testing.
References
==========
* https://etherpad.openstack.org/p/austin-docs-toolsinfra

200
specs/newton/improve-glossary-usage.rst
View File

@ -1,200 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
====================================
Improve usage of glossary in manuals
====================================
Include the URL of your launchpad blueprint:
https://blueprints.launchpad.net/openstack-manuals/+spec/improve-glossary-usage
There are 712 terms defined in the glossary.
There are 165 references to the glossary terms throughout the
openstack-manuals repo.
The glossary exists to explain terms in the context of OpenStack, so that users
don't have to look up terms that they are unfamiliar with and try to fit it
back into the right context.
This is only useful if:
* users can easily access the glossary (i.e. link to glossary in docs).
* the glossary is not over burdened with acrynoms or terms that are not
specific to OpenStack
Problem description
===================
OpenStack is a large project, with many different components and use cases. One
major issue that people have when trying to set up OpenStack is that there are
so many moving parts and different use cases. People trying to deploy,
configure and use OpenStack aren't necessarily going to be familiar with all
the components, technologies or terminology associated with OpenStack.
There is a glossary which accompanies the OpenStack manuals, which provides
definitions for many of these terms. However, there is relatively little
reference to this useful resource in the manuals, so users/deployers may not
be aware of the existance of the glossary, and spend time looking up these new
terms only to have to fit them back into the context of OpenStack, which might
be a new concept to them. This can lead to OpenStack being perceived as
difficult to grasp, and hard to ramp up on.
Proposed change
===============
The proposed change would add links to glossary terms in the manuals so that
users can easily access descriptions of unfamiliar terms within the context of
OpenStack. This is so that users have a better experience and can come to terms
with OpenStack terminology quicker than if they had to look up the term and
figure out how it relates to/is used in OpenStack.
There are two step in this process (with multiple sub steps):
* Remove acronyms/generic terms
* Link terms from the glossary to the books
**Step 1: remove acronyms/generic terms**
The first step is removing unnecessary terms from the glossary.
In order to achieve that, we'd need to decide what the unnecessary terms were.
This is likely to be time consuming in terms of reviews. In terms of proposed
removals, the suggested method is:
* Identify criteria for removal:
* Acronyms
* Generic terms (terms defined in the glossary should include HOW they are
related to OpenStack)
* Propose patches for each set of criteria in alphabetical chunks:
- e.g. [glossary] Remove acronyms [A-B]
**Acronyms** are the easiest place to start.
An acronym shouldn't have a definition of it's own, it should be part of the
relevant entry::
# Good entry, the commonly used acronym is included in the entry heading
IP Address Management (IPAM)
The process of ....
# this entry is bad because it just expands the acronym
IPL
Initial Program Loader.
An entry that passes the first test doesn't necessarily get through on round
two, but it keeps things clean as the content is refactored.
For determining generic terms to remove, valid terms must be defined. Any term
falling outside the criteria of valid is up for removal.
A **valid term** is:
* Specfic to OpenStack e.g. *tenant*, *project*, *compute node*
This is a term that doesn't exist or is used in a different way outside of
OpenStack.
* Codename for a project e.g. *nova*, *neutron*, *keystone*
In these cases, the code name is the entry, and the service is not::
# This is an unnecessary entry, because the term readers would be looking
# for is Trove, not database service
Database Service
... The project name of Database service is trove.
* In most occurances, the service name/code name can be combined into a
larger entry.
* Generic terms, defined in the context of its usage in OpenStack
* Supported technologies are not valid, as this would be clear from the
manuals where it is mentioned (same is true for drivers)
* Exception: the technology is used in a non-standard way
* Litmus test: Will an internet search return the same information?::
# Bad - technology used in OpenStack, in a standard way
SQL-Alchemy
An open source SQL toolkit for Python, used in OpenStack.
**Step 2: Link terms from the glossary to the books**
The second part of this change is to make sure the glossary is used. This step
links relevant terms from the manuals to the glossary entries.
This can be done on a per-book basis in the following way (depending on the
size of the book and the number of terms):
* Iterate through the glossary terms and determine whether they are used in
the book
* Group the terms into managable chunks::
[glossary] admin-guide links [A-D]
* Only the first occurance in a chapter should be linked
**Review process**
For straightforward reviews, each set of changes is proposed for removal.
If there are any contentious terms, these will be removed from the main review,
and proposed individually, so that most of the work can take place as quickly
as possible, and not get blocked because there are strong opinions about an
exceptional term.
Alternatives
------------
None
In this case, all the parts are present, but they have to be better
connected/accessible.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
emma-l-foley
Other contributors:
TBD
Work Items
----------
* Clean up the glossary
* Remove acronyms
* Remove unnecessary/generic terms
* Improve usage of the glossary
* Add links to each book
Dependencies
============
None
Testing
=======
No additional testing should be required.
The ability to check if a glossary term exists is already present, and can be
used to ensure that there are no invalid links.
References
==========
Mailing list thread:
http://lists.openstack.org/pipermail/openstack-docs/2016-July/008915.html

180
specs/newton/installguide.rst
View File

@ -1,180 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=========================
Newton Installation Guide
=========================
Problem description
===================
With the growing OpenStack Big Tent, many projects need to create
install guides, new infrastructure is planned to enable projects to write
and maintain their own install guides, and to have them published on
docs.openstack.org as first class OpenStack citizens. As a complement to
this, the current install guide needs to be updated and improved to ensure
it remains a good source of installation information, with an increased
focus on the fact that the install guide is used as training material, and
is not recommended as a way to install clouds for production.
This spec proposes some changes to the install guide to meet this end, and
is the product of discussion at the Newton design summit (see references).
Proposed change
===============
The basic install guide serves as a reference to reach the
first step where administrators have all the underlying services like
MySQL and RabbitMQ and a base set of functionality installed and
working. It is essential for every reader of the guide to have
high-quality, proactively-checked, easy-to-understand content. The intent for
a central, basic install guide is to train and orient readers so they can
understand multiple OpenStack services while making informed decisions for
their situation.
Then additional project-specific guides can be written that pick up
from that base first step, assuming their readers have completed that
first step successfully.
Scope of basic install guide
----------------------------
The content of the basic install guide will cover the infrastructure and
centralized projects that every cloud needs. This includes the defcore
projects defined as
`starter-kit:compute
<http://governance.openstack.org/reference/tags/starter-kit_compute.html>`__
plus a few others:
* Compute service (nova): Part of starter-kit:compute.
* Image service (glance): Part of starter-kit:compute.
* Identity service (keystone): Part of starter-kit:compute.
* Networking service (neutron): Part of starter-kit:compute.
* Block storage service (cinder): Part of current install guide and
expected by most users.
* Dashboard (horizon): Part of current install guide and expected by
most users.
No further projects will be added to the guide unless they are
required by one of the existing projects or generally required to run
an OpenStack based cloud.
The documentation team updates and tests the basic install guide for
each release.
The install guide will be enhanced to link to additional project
specific install guides. For this, it will have in a separate chapter
for each official project a small section where each official project
can give a short summary of their project together with a link to
their own install guide. The chapter will also explain that all these
projects are first-class citizens of the big tent of OpenStack.
For example, Orchestration could store their install guide in the ``heat``
repository, and publish to
http://docs.openstack.org/project-install-guide/mitaka/orchestration/ .
Then the chapter "Additional projects" would contain a small section
to introduce the service and link to it:
.. code::
Orchestration service (heat)
============================
The Orchestration service ...
Installation is documented at
http://docs.openstack.org/project-install-guide/mitaka/orchestration
.
Docs.openstack.org index
------------------------
The project specific install guides will be listed not only in the
install guide but also be found from the docs.openstack.org web page.
An exact location will need to be found based on the number of guides.
Alternatives
------------
* Packaged install guides separated out, with no single-sourced install guide:
each distribution publishes their own installation guide. These guides can
be published to docs.openstack.org/install or to a web domain they own,
sourced and reviewed from their own repositories with their teams. These
teams can set their own publishing schedule. This alternative solution
does not address the project teams needs, but alleviates the resource drain
on a centralized docs team.
* Stop writing package-based install guides in the OpenStack git namespace
entirely. Instead, have a central team write a starter-kit-based guide that
describes the multiple available deployment options and publish to
docs.openstack.org. This solution may be already available when readers
browse the distro marketplace at
https://www.openstack.org/marketplace/distros/.
* Each project team can write an "installation from source" installation
guide that includes all the basic project infrastructure set up.
* Change scope of install guide, add a few more or less projects as
proposed in this spec to it. This does not address the current single-
sourcing with packages problem described, however.
* Status quo: One central install guide that is maintained by the
documentation team and no project specific guides for those projects
that are not part of the central guide. This approach does not scale
unless we receive a commitment of resources from each project in the
installation guide.
* One central guide that is reviewed by the documentation team - like
today - and only projects are documented when the project team has
committed writing, testing, and updating the chapter.
This does not scale since reviewing would still be done by the
documentation team. Experience in the past has shown that project
teams need to be reminded of their commitment, so in the end the
documentation team would play a large coordination and shepherding
role for such a large guide - instead of following the enablement
role that is sought by this proposal.
Implementation
==============
Assignee(s)
-----------
* Lana Brindley (loquacities) - Docs PTL
* Andreas Jaeger (AJaeger) - Infrastructure
* Install Guide Speciality Team
Work Items
----------
* Update the title (what to?) to reflect that it is for training and not
production, and add preamble to explain that purpose.
* Document from packages to best use existing content, but continue to
revisit this problem over time, as more data emerges about which
installation method users prefer.
* Edit the existing content so that it uses manual configuration only.
* Create scripts that can be run and automatically tested and include
snippets of these scripts verbatim in the guide. This will accelerate
testing of the guide.
* Create a 'cookie cutter' template that can be used for all services
(AJaeger): https://review.openstack.org/#/c/314229/
* Document the process of adding a big tent project under the new governance,
including what tests and dependencies are required.
* Move Shared File Systems (Manila), Object Storage (Swift), Orchestration
(Heat), Telemetry (Ceilometer), Database (Trove) to project repositories
and link them in the "Additional projects" chapter.
Dependencies
============
Testing
=======
References
==========
* https://etherpad.openstack.org/p/austin-docs-workgroup-install

248
specs/newton/project-specific-installguides.rst
View File

@ -1,248 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===============================
Project-specific install guides
===============================
Problem description
===================
With the growing OpenStack Big Tent, many projects need to create
install guides. The current install guide is concentrating on a small
set of projects and gets tested each release. Documenting and testing
all projects in the install guide is not possible with the current
size of the OpenStack documentation team.
We therefore need to find a way that allows projects to write their
own install guides without involvement of the documentation team -
and the documentation team acting as enabler for these documents.
Proposed change
===============
The basic install guide serves as a reference to reach the
first step where administrators have all the underlying services like
MySQL and RabbitMQ and a base set of functionality installed and
working. It is essential for every reader of the guide to have
high-quality, proactively-checked, easy-to-understand content. The intent for
a central, basic install guide is to train and orient readers so they can
understand multiple OpenStack services while making informed decisions for
their situation.
Then additional project-specific guides can be written that pick up
from that base first step, assuming their readers have completed that
first step successfully.
Ownership of the project specific install guides is with the
respective project team, not the documentation team. This means the
content is in an existing or new repository owned by the project team,
reviews will be done by the project team, and bug reports will go in
the bug queue of the project.
The documentation team enables the project team to write the
project specific guides with mentoring, setting up needed
infrastructure, writing guidelines, provision of a template ("cookie
cutter"), and providing a working base install guide that the project
specific guides can use as reference.
Scope of basic install guide
----------------------------
The content of the basic install guide will cover the infrastructure and
centralized projects that every cloud needs. This includes the projects defined
as the
`starter-kit:compute
<http://governance.openstack.org/reference/tags/starter-kit_compute.html>`__
plus a few others:
* Compute service (nova): Part of starter-kit:compute.
* Image service (glance): Part of starter-kit:compute.
* Identity service (keystone): Part of starter-kit:compute.
* Networking service (neutron): Part of starter-kit:compute.
* Block storage service (cinder): Part of current install guide and
expected by most users.
* Dashboard (horizon): Part of current install guide and expected by
most users.
No further projects will be added to the guide unless they are
required by one of the existing projects or generally required to run
an OpenStack based cloud.
The documentation team updates and tests the basic install guide for
each release.
The install guide will be enhanced to link to additional project
specific install guides. For this, it will have in a separate chapter
for each official project a small section where each official project
can give a short summary of their project together with a link to
their own install guide. The chapter will also explain that all these
projects are first-class citizens of the big tent of OpenStack.
For example, Orchestration could store their install guide in the ``heat``
repository, and publish to
http://docs.openstack.org/project-install-guide/mitaka/orchestration/ .
Then the chapter "Additional projects" would contain a small section
to introduce the service and link to it:
.. code::
Orchestration service (heat)
============================
The Orchestration service ...
Installation is documented at
http://docs.openstack.org/project-install-guide/mitaka/orchestration
.
Docs.openstack.org index
------------------------
The project specific install guides will be listed not only in the
install guide but also be found from the docs.openstack.org web page.
An exact location will need to be found based on the number of guides.
Content of project specific install guides
------------------------------------------
The content of these project specific install guides is outside of the
control of the documentation team. For consistency with the base
install guide architecture and as part of the "enabling others" part,
the documentation team has some suggestions:
* We encourage projects to build on top of the existing install guide
architecture. This way the project team guide does not need to
document a full OpenStack setup including the basic host setup.
Instead of reinventing the wheel, the project team guide can just
point out differences for the specific project.
* We encourage projects to follow the documentation conventions as
written down in the `Documentation Contributor Guide
<http://docs.openstack.org/contributor-guide/>`__.
* We encourage projects to use the same theme (called
``openstackdocstheme``) as the install guide.
* We encourage projects to support the same distributions as the
install guide does. They can either document installation of
OpenStack packages from distributors or installation from source.
* Project specific guides should be versioned, so project teams should
publish to the respective subdirectory for their service.
* RST is the preferred documentation format and our tools for
publishing work best with it. Also, translation of RST guides is
easy to set up and working in the OpenStack CI infrastructure.
Therefore, project teams should use RST as format.
* The project team installation guides should have a common naming
scheme: "X Service install guide" where X is the service name
from the governance repository. So, for example "Orchestration
Service install guide".
Publishing
----------
Project teams can publish their content to
``docs.openstack.org/project-install-guide/RELEASE/SERVICE/ ``. ``RELEASE`` is
the release like ``mitaka`` or ``newton``, ``SERVICE`` is the service
name like ``orchestration``. For publishing from master, the
``RELEASE`` should be ``draft``.
This structure takes care that we do not share directories for
different projects.
Alternatives
------------
* Packaged install guides separated out, with no single-sourced install guide:
each distribution publishes their own installation guide. These guides can
be published to docs.openstack.org/install or to a web domain they own,
sourced and reviewed from their own repositories with their teams. These
teams can set their own publishing schedule. This alternative solution
does not address the project teams needs, but alleviates the resource drain
on a centralized docs team.
* Stop writing package-based install guides in the OpenStack git namespace
entirely. Instead, have a central team write a starter-kit-based guide that
describes the multiple available deployment options and publish to
docs.openstack.org. This solution may be already available when readers
browse the distro marketplace at
https://www.openstack.org/marketplace/distros/.
* Each project team can write an "installation from source" installation
guide that includes all the basic project infrastructure set up.
* Change scope of install guide, add a few more or less projects as
proposed in this spec to it. This does not address the current single-
sourcing with packages problem described, however.
* Status quo: One central install guide that is maintained by the
documentation team and no project specific guides for those projects
that are not part of the central guide. This approach does not scale
unless we receive a commitment of resources from each project in the
installation guide.
* One central guide that is reviewed by the documentation team - like
today - and only projects are documented when the project team has
committed writing, testing, and updating the chapter.
This does not scale since reviewing would still be done by the
documentation team. Experience in the past has shown that project
teams need to be reminded of their commitment, so in the end the
documentation team would play a large coordination and shepherding
role for such a large guide - instead of following the enablement
role that is sought by this proposal.
Implementation
==============
Assignee(s)
-----------
* Lana Brindley (loquacities) - Docs PTL
* Install Guide Speciality Team
Work Items
----------
* Move projects that are now out of scope of the basic install guide
into in their own repositories. Also, create initial skeleton for
these project specific install guides so that project teams have a
consistent starting point that others can follow as example.
This affects: Orchestration (heat), Telemetry (telemetry), Object
Storage (swift), Shared File system (manila).
* Create new chapter "project specific install guides" as skeleton.
* Create new project-specific install guides section on
http://docs.openstack.org .
* Create example jobs for publishing of project-specific install
guides (jaegerandi).
* Work with operator tags team to amend the `ops:docs:install-guide tag
<http://git.openstack.org/cgit/openstack/ops-tags-team/tree/descriptions/ops-docs-install-guide.rst>`_
(thingee)
* Create a "cookie cutter" template for use by projects when creating
new Install Guides.
Dependencies
============
Testing
=======
References
==========
* http://lists.openstack.org/pipermail/openstack-dev/2016-March/090214.html
* https://www.openstack.org/assets/survey/April-2016-User-Survey-Report.pdf
* https://review.openstack.org/#/c/310588/

131
specs/newton/release-notes-guidelines-to-cg.rst
View File

@ -1,131 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
========================
Release notes guidelines
========================
https://blueprints.launchpad.net/openstack-manuals/+spec/release-notes-guidelines-to-cg
To maintain the overall quality of the OpenStack documentation,
the release notes guidelines should be developed and published.
Problem description
===================
As a developer who creates the release notes for the OpenStack project
I contribute to, I would like to have clear and concise writing style
guidelines for the release notes as well as a handy list of all
sources of information regarding release notes management within
the project.
Proposed change
===============
The proposed change is to add the following information to the Contributor
guide:
* Release notes sections, what is included where
* Writing style guidelines (verb forms, sentence structures, links inclusion,
etc.)
* Release notes *bad -> improved* examples
* Reno overview for general understanding of how things work there.
* The list of links where different pieces of release notes related
information can be found (Reno docs, project team guide, etc).
Alternatives
------------
We can add these recommendations to the `Project Team guide <http://docs.openstack.org/project-team-guide/release-management.html>`_,
`Infra manual <http://docs.openstack.org/infra/manual/developers.html>`_,
or `Reno documentation <http://docs.openstack.org/developer/reno/>`_.
Despite of the fact that these locations may fit (mainly because
they are targeted at developers who create release notes for projects),
there are strong arguments in favor of the Contributor guide:
* *Project Team guide* mostly discusses adjusting a project's repo
to use the release management tool rather than release notes writing
style.
* *Infra manual* contains only general workflow of contributing to
OpenStack source code repositories rather than specific use-cases such as
the release notes creation.
* *Reno documentation* - though it is fully dedicated to the release notes
creation process and shaped for the developers (our main intended audience),
this is just a tool that can be replaced in future with another release
notes management tool with its own documentation.
To sum up, Contributor guide still remains the best place to document
release notes writing style guidelines for a number of reasons:
* Release notes are part of documentation
* Contributor guide`s intended audience is documentation contributors.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Olga Gusarenko <ogusarenko>
Work Items
----------
The work items include the following:
* Create the overview of Release notes sections, what include where.
* Develop the writing style guidelines (release notes specific).
These include:
* Verb forms
* Sentence structures for different types of release notes (New features,
Bug fixes, etc.)
* Links inclusion
* Make up bad examples of release notes and rework them.
Present them in a form of *bad -> improved* examples for better illustration.
* Create Reno overview for general understanding of how things work there and
why Community uses it to manage release notes.
* Create subsection ("Additional resources") that lists links, where different
pieces of release notes related information can be found, with brief
descriptions.
* Cross-references:
* `Project Team guide <http://docs.openstack.org/project-team-guide/release-management.html#how-to-add-new-release-notes>`__
* `Reno documentation <http://docs.openstack.org/developer/reno/>`_
* `Infra manual <http://docs.openstack.org/infra/manual/developers.html>`_
* Inform OpenStack developers about the release notes guidelines when
published:
* Through the openstack-dev mailing list
* Add the release note to documentation release notes for Newton
Dependencies
============
n/a
Testing
=======
n/a
References
==========
* `Contributor Guide Austin Session notes <https://etherpad.openstack.org/p/austin-docs-contributorguide>`_.
* `Reno documentation <http://docs.openstack.org/developer/reno/>`_.
* Current instructions for the developers
`Managing Release Notes <http://docs.openstack.org/project-team-guide/release-management.html#how-to-add-new-release-notes>`_.

77
specs/newton/training-labs-pxe-server.rst
View File

@ -1,77 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=======================
Trainig-labs PXE server
=======================
URL of the launchpad blueprint:
https://blueprints.launchpad.net/openstack-manuals/+spec/pxe-server-osbash
Training-labs traditionally installs OpenStack on Virtual Machines on the
local machine. This feature should allow training-labs to provide PXE boot
functionality for installing the OpenStack cluster on bare-metal.
Training-labs at present builds the framework to install a Virtual Machine
(VM). Adding Preboot eXecution Environment (PXE) server as a VM in the
cluster should provide the bare-metal machines (physical hardware) or
optionally even Virtual Machines with the supported linux distributions
for installing and running OpenStack on top of it.
Setting this VM with bridged networking would allow us to make this PXE
server easily accessible from the physical machine (laptop/desktop/server/
VM/etc.) and install the OpenStack cluster using the existing deployment
solution and policies of training-labs on real hardware.
Proposed change
===============
To enable PXE boot feature the following changes would be necessary:
* Adding PXE Server node to osbash.
* Changing osbash CLI to add ``pxeserver`` option.
* Installation and configuration scripts for PXE server.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* Julen Larrucea (julenl)
Other contributors:
* Pranav Salunke (dguitarbite)
* Roger Luethi (rluethi)
Work Items
----------
* Add new scripts which would allow PXE boot scenarios in training-labs.
* Selecting the right way for automated installation of the operating
system.
* Creating appropriate policies for identifying the given role of a server.
* Adding bridge network to the existing cluster.
Testing
=======
Run:
./osbash.sh -b pxeserver
The machine will be accessible in subnet of the bridged interface with the
last octet being ``100``. If we are using the default networks, this could
be ``10.0.0.100``. The login credentials are the default ones for osbash.
References
==========
* The boot menu for the PXE provision is similar to the one in BOMSI:
https://github.com/julenl/BOMSI/tree/master/Ubuntu-Liberty

156
specs/newton/ui-heuristic-checklist.rst
View File

@ -1,156 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===============================================
Add UI heuristic checklist to Contributor Guide
===============================================
https://blueprints.launchpad.net/openstack-manuals/+spec/ui-heuristic-checklist
Add an OpenStack UI heuristic checklist within the OpenStack
Documentation Contributor Guide under the UI guidelines section.
Problem description
===================
The OpenStack UX project is interested in adding a section to the
OpenStack Documentation Contributor Guide that provides a
graphical user interfaces (GUI) heuristic checklist developed by the
OpenStack project teams: UX and ID with input from Horizon and
OpenStack CLI. The content is connected to the UI text guidelines we
published for Mitaka.
Heuristic evaluations are a simple inspection method that allows
engineers and designers to review designs for common usability issues.
The benefits are that heuristics are low-cost and relatively easy to use
for individuals that are evaluating a design. An additional benefit of
heuristics is that they help maintain consistency and transparency in how
multiple designs are reviewed.
An example of a heuristic includes the "10 Usability Heuristics for
User Interface Design" developed by Jakob Nielsen in the 1990's that
includes principles for error recovery and system status. The OpenStack
community heuristic includes principles that are specific to developing
for the cloud and include a focus on designing to scale along with examples
such as the number of images within a typical production deployment.
The working draft of these guidelines is in progress and can be viewed
here: https://etherpad.openstack.org/p/mitaka-openstackux-heuristic
The value of this effort is to help provide an improved
usability for operators, admins, and end users by creating
tools that help promote consistency in OpenStack GUI interfaces.
Proposed change
===============
In a new UX/UI section of the contributor guide, add a topic for the
UI heuristic checklist. The heuristic checklist could be
added as a peer to both the UI text guidelines (already exist) and to
the (proposed) UX personas section within the OpenStack
Documentation Contributor Guide.
Proposed table of contents:
UX/UI guidelines (section title updated to reflect broader scope)
* Value/Intro
* UI text guidelines (already exist)
* UI heuristic checklist (new, proposed by this spec)
* UX personas (new, proposed in separate spec)
Alternatives
------------
#. Do not add UI heuristic checklist.
#. Add checklist, but create it in a new guide for UX design.
An email was distributed to the doc project regarding
the idea of a new UX design guide to house UX-related
resources and tools for a cross-project audience.
These were the options discussed in the email, sent 3/7/16.
Please see email for more detail and history.
Option A
Create a OpenStack UX Design Guide: Tools for
developers guide, under the Contributor Guides section
on docs.openstack.org. The guide would house UX design materials,
like engaging UX, personas, use cases, resources section with
heuristic checklists, etc. Basically, creating a design corner
concept with guide name tbd.
* Pros: Peer to other contributor guides - creates a more
prominent focus on UX/UI design in OpenStack, we could reference
guide from appropriate locations to increase visibility
* Cons: New guide - logistics more complicated, logistics help needed
Takes longer to get reviews going
Option B: Add to the existing Doc Contributor Guide, but modify the
guide's scope.
* Pros: Existing guide - logistics easier, content would be available
to review sooner UI guidelines content in one location
(The new UI heuristic checklist links to the UI text guidelines
that we recently added to the doc contributor guide.)
* Cons: Not just for text guidelines anymore, so the guide's current
scope would expand slightly to include a section specifically on
UX/UI tools for a cross-project audience.
Option C: Add to the existing Doc Contributor Guide as-is,
potentially adjust later...
* Pros: Content available for review quickly, lowest logistical
impact
* Cons: scope could be confusing for users, adjusting later
delays some work
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* pkruithofjr@gmail.com
* stemke@us.ibm.com
Other contributors:
* gmolson@us.ibm.com
* nancy.ann.michell@hpe.com
* openstack@lanabrindley.com
* rcresswe@cisco.com
Work Items
----------
* Reach a consensus on new section's location and content structure.
* Identify new topics to be created and submit content/reviews using the
[blueprint ui-hueristic-checklist] tag.
Dependencies
============
This work is a collaboration between the UX and Doc team that requires
UX project team input and creation of the heuristic checklist.
Testing
=======
Testing will follow the standard documentation review process.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with
[ui-heuristic-checklist] in the subject.
.. _`documentation team meeting`:
https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

123
specs/newton/user-guide-edit.rst
View File

@ -1,123 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===============================
User Guides Consistency Editing
===============================
Problem Description
===================
After the docs changes and rebuilds during the Mitaka release cycle,
several editing items that touched both the OpenStack Administrator
and OpenStack User Guide remained. This spec makes these
items a priority for Newton. It also introduces work items that have
been raised on the docs mailing list or in reported bugs.
Proposed Change
===============
Edit the tables and code snippets to ensure they appear consistent
across the OpenStack Administrator Guide and the OpenStack User Guide.
Use the information on Personae in the OpenStack Contributor Guide to
confirm that chapters in the Administrator Guide, and content appearing
within chapters, is informative for the audience. Link together certain
sections in the guides when appropriate: for example "For more information
on Migrating Volumes, see the OpenStack User Guide".
Make specific adjustments to the Information Architecture - where content
appears in specific chapters:
* Networking - Configuring Identity for Networking. Move the note earlier.
* Block Storage - persistent storage needs to appear earlier.
* Secure with Rootwrap - Move and rework the architecture of the FAQ section.
Plus, other sections as needed.
Include new diagrams for the security hardening content, specifically,
improve the OpenStack with Trusted Compute Pools Second diagram. A new
diagram needs headings and consistency with the other diagrams.
Replace the legacy client commands with up-to-date OpenStack CLI commands
in all examples in the User Guide.
Alternatives
------------
* Complete the proposed changes as individual bugs instead of a blueprint.
* Leave the guides as they are.
Implementation
==============
Assignee(s)
-----------
* Joseph Robinson
* Any Contributors associated with the User Guide, or interested in
contributing to the User Guide Information Architecture.
Work items
----------
Chapters and edits proposed:
Administrator Guide
* Telemetry - adjust code snippets.
* Networking - Adjust tables in the Use Networking section.
* Secure with Rootwrap - tables here were code snippets. Restore them or
adapt the content.
* Flavours - The tables in this section have bold headings. Adjust this
design choice across the User Guides.
* Nova Networking - The table Configure Compute to use IPv6 addresses
needs consistency across the User Guides.
* Block Storage - Migrate Volumes and Back up and Restore volumes need
adjustments to their audience. Confirm they fit the audience, or adapt
to fit into the User Guide. Connect nova-image list content to the
User Guide. Move the persistent storage content earlier in the Back up
and Restore volumes chapter. Move the Rate Limit content closer to the
information on migrating Block Storage Volumes. Move the storage
service quotas information.
* Networking - Rework Networking tables for consistency. Adjust
placement of admonitions, and Networking Architecture information.
* Security - An improved security hardening for the Trusted Compute
Pools section.
User Guide
* Adapt the legacy command line client content, updating the examples to
use the more recent OpenStack command line client.
Dependencies
============
This spec is intended as a work item for the Newton release, however with
time and volunteer numbers, some of these items may not be completed in
time for release.
The **priority items** that can most likely be completed are:
* table consistency
* diagram improvements
* updates from legacy commands to the openstack
client command.
Testing
=======
Ensure the document builds with new tables and diagrams
References
============
Work on the User Guide update for the legacy command line clients has
begun with the
`Use OpenStack command to replace other commands blueprint <https://blueprints.launchpad.net/openstack-manuals/+spec/use-openstack-command>`_.

166
specs/newton/ux-personas.rst
View File

@ -1,166 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==============================================
Add UI content guidelines to Contributor Guide
==============================================
https://blueprints.launchpad.net/openstack-manuals/+spec/ux-personas
Add OpenStack personas within the OpenStack
Documentation Contributor Guide under the UI guidelines section.
Problem description
===================
The OpenStack UX project is interested in adding a section to the
OpenStack Documentation Contributor Guide that describes personas
developed by the OpenStack UX project team.
Users can apply personas to development design decisions,
use personas as IA resources for new and changing guide
evaluating requirements, guides, and employed in possible
marketing collateral.
The value of this effort is to help provide developers,
designers, and reviewers with an improved awareness
of OpenStack users. With this awareness, they can
design and develop OpenStack with the appropriate
audience goals, and resulting task flows, in mind.
Personas help establish consistency across projects, increase
awareness for the customer and their goals, and
communicate the differences between specific customers.
Proposed change
===============
In a new UX/UI section of the contributor guide, add a topic
collection for personas. The personas section could be
added as a peer to both the UI text guidelines (already exist) and to
the (proposed) UI heuristic checklist section within the OpenStack
Documentation Contributor Guide.
Proposed table of contents:
UX/UI guidelines (section title updated to reflect broader scope)
* Value/Intro
* UI text guidelines (already exist)
* UI heuristic checklist (new, proposed in separate spec)
* UX personas (new, proposed by this spec)
In the personas section, the following personas will be elaborated
upon.
Cloud Personas
~~~~~~~~~~~~~~
The personas information will be based upon model companies and
their ecosystems. They describe the cloud adoption stages and
describe multiple roles defined with each company. Roles that
perform similar tasks may be called something different in each
company. It is also common for the same person to perform
multiple roles or shared tasks. Early research
shows that the role ecosystem is complex and diverse.
Contact Piet Kruithof (See :ref:`assignee` below) for the
most recent version of the personas.
Alternatives
------------
#. Do not add UX personas.
#. Add personas, but create them in a new guide for UX design tools.
An email was distributed to the doc project regarding
the idea of a new UX design guide to house UX-related
resources and tools for a cross-project audience. These were
the options discussed in the email (sent 3/7/16). Please see
the docs mailing list or OpenStack email archive for
more details and history.
Option A
Create a OpenStack UX Design Guide: Tools for
developers guide, under the Contributor Guides section
on docs.openstack.org. The guide would house UX design materials,
like engaging UX, personas, use cases, and a resources
section with a heuristic checklists, etc. Basically, creating
a design corner concept. Guide name is to be decided.
* Pros: A peer to other contributor guides. Creates a more
prominent focus on UX/UI design in OpenStack. We could reference
the guide from appropriate locations to increase visibility.
* Cons: New guide-logistics are more complicated - logistics help
needed. This option takes longer to get reviews going.
Option B
Add to the existing Doc Contributor Guide, but modify the guide's scope.
* Pros: Existing guide-logistics easier, and content would be
available to review sooner. The UI guidelines and content
would be in one location.
The new UI heuristic checklist links to the UI text guidelines
that we recently added to the doc contributor guide.
* Cons: Not just for text guidelines anymore, so the current
guide scope would expand slightly to include a section
specifically on UX/UI tools for a cross-project audience.
Option C
Add to the existing Doc Contributor Guide as-is, potentially adjust later.
* Pros: Content available for review quickly, lowest logistical impact.
* Cons: Scope could be confusing for users, adjusting later delays
some work.
Implementation
==============
.. _assignee:
Assignee(s)
~~~~~~~~~~~
Primary assignee:
* pkruithofjr@gmail.com
* stemke@us.ibm.com
Other contributors:
* gmolson@us.ibm.com
* nancy.ann.michell@hpe.com
* openstack@lanabrindley.com
* rcresswe@cisco.com
* jamielennox@gmail.com
* jacalcat@us.ibm.com
Work Items
~~~~~~~~~~
* Reach a consensus on new section location and content structure.
* Identify new topics to be created and submit content/reviews using the
[blueprint ux-personas] tag.
Dependencies
============
This work is a collaboration between the UX and Doc team that requires
input from both projects.
Testing
=======
Testing will follow the standard documentation review process.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with
[ux-personas] in the subject.
.. _`documentation team meeting`:
https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

169
specs/ocata/arch-guide-restructure.rst
View File

@ -1,169 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=====================================
Architecture Design Guide Restructure
=====================================
Problem description
===================
The current Architecture Design Guide is primarily organized by use case.
However, a combination of features from different use cases is often used when
designing an OpenStack cloud.
It is recommended to restructure content so the user can consider all the
requirements when designing an OpenStack cloud. Additional information should
be provided when designing an OpenStack cloud in a development, staged or
production environment. The proposal is to revise the content
structure to refine use cases to the most common OpenStack deployments, and
also create an abstraction between cloud architecture concepts and various
OpenStack projects. This will make it easier to maintain the guide.
Proposed change
===============
The proposed structure of the guide is to first describe common cloud use
cases, then general architectural concepts, followed by cloud architecture
design with a detailed breakdown of the major cloud architecture components.
Proposed table of contents
--------------------------
The proposed structure for the updated Architecture Design Guide is as follows:
#. Overview
#. Use cases
#. Development cloud
#. General compute cloud
#. Web scale cloud
#. Storage cloud
#. Network Function Virtualization (NFV) cloud
#. High Availability
#. Capacity planning and scaling
#. Adding cloud controller nodes
#. Segregating your cloud
#. Scalable hardware
#. Design
#. Compute
*Implementation of the compute platform including
hypervisors, nova, and ironic*
#. Storage
*Storage choices and the implementation of
projects such as cinder and manila.*
#. Networking
*Networking design choices such as SDN, LBaaS,
and neutron.*
#. Identity
*Authentication, authorisation, and assignment at
all levels for keystone and related projects.*
#. Image
*Management, creation, distribution, and
deployment of images for glance and related projects.*
#. Control Plane
*General implementation of the OpenStack control components and the
decision making that goes into the choices that need to be made.*
#. Dashboard and APIs
*Interaction with cloud services using a graphical interface or the
OpenStack APIs. This would include horizon and other Cloud Management
Platform (CMP) tools.*
The Use Cases chapter will contain the five most common OpenStack use cases. It
will describe the scope and requirements, which will be a
precursor for reference architecture information. For each use case, the
section headings would be as follows:
#. Design model
#. Requirements
#. Reference architecture
The sub-section headings in the Design chapter would be as follows:
#. Technical detail
#. Capacity and scale
#. High availability
#. Operator requirements
#. Deployment considerations
#. Maintenance considerations
The headings are intended as a guideline to the type of information that should
be provided. It will be used only when there is a specific need to provide
information.
Alternatives
------------
Leave the guide as is.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* dazzachan
Other contributors:
* shaunom
* tersian
* alexandra-settle
Work items
----------
* Migrate the Architecture chapter in the Operations Guide to the
Architecture Design Guide
* Multiple contributors to write content
* Identify information gaps and submit patches
Dependencies
============
Contributions and input from cloud solution architects.
Testing
=======
Testing will follow the standard documentation review process.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [arch-guide]
in the subject, biweekly Ops Guide specialty team meeting,
weekly documentation team meeting, and the Arch Guide working group meeting.
* `Draft Architecture Design Guide <http://docs.openstack.org/draft/arch-design-draft/>`_
* `Etherpad <https://etherpad.openstack.org/p/arch-guide-reorg-ocata>`_
.. _`Ops/arch tasks etherpad`: https://etherpad.openstack.org/p/ops-arch-tasks

142
specs/ocata/build-pdf-from-rst-guides.rst
View File

@ -1,142 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=============================================
Build PDF docs from rst-based guide documents
=============================================
https://blueprints.launchpad.net/openstack-manuals/+spec/build-pdf-from-rst-guides
Generating PDF doc files for current openstack-manuals documents
and providing PDF download URLs to each HTML document is helpful for
users who want to see documents offline.
Problem description
===================
DocBook XMLs have been successfully migrated and converted
into RST sources. OpenStack RST-sourced documentation uses Sphinx
to build HTML documents and publish them on docs.openstack.org.
And openstackdocstheme is responsible for the theme and extension
in the published HTML documents.
One desired functionality in RST-sourced documents is to have PDF
versions of the books. Current HTML documents are surely helpful,
but having PDF versions provides OpenStack documentation readers
with more additional benefits. For example, users can download PDF files
and read them offline. To print HTML documents, users do more manual
steps such as moving from one page to other pages and the printed layout
is different from what users see through monitors. Furthermore,
it is easier for users to share their personal notes in PDF files with
other readers. One more advantage using PDF files is that PDF files have
pages. It is useful for offline training environment with printable
OpenStack documents by indicating page numbers.
Proposed change
===============
Add the support of building PDFs using current Sphinx build
infrastructure using RST-sourced files in openstack-manuals repository.
Generating PDF files using RST-sourced files includes two steps in workflow.
First, Sphinx generates LaTeX files (.tex) from RST-sourced files.
Second, pdflatex generates PDF files from generated LaTeX files.
After the combination of Sphinx and LaTeX supports PDF file generation,
apply PDF buildings to all the HTML documents in openstack-manuals repository
using LaTeX PDF generation. And add the build job to work with HTML builds,
publish PDF files on docs.openstack.org per each document build,
and finally insert PDF download URLs in the landing page of HTML documents.
Note that the main change will happen in openstack-doc-tools
for scripts, openstackdocstheme for possible additional themes for PDFs,
and each documentation repository such as openstack-manuals to add
PDF build support in Sphinx configurations.
Alternatives
------------
* Building PDFs separately (without using current Sphinx build scripts)
can be an alternative. However, this result will decrease the manageability
of build scripts in documentation repositories.
* Document how users can built PDFs locally but do not publish PDFs.
* Leave the guide with current HTML build infrastructure as is.
Implementation
==============
Assignee(s)
-----------
* ianychoi
* nexusz99
* jangpro2
* raymon-ha
* seungkyua
* sungjin
Work Items
----------
* Identifying requirements of libraries
* Checking the compatibility of the libraries
* Changes in Sphinx configuration
* A basic PDF theme (fancy theme design is not the main goal)
* Suggested minimums
* title page
* accurate page numbers
* table of contents entries and links to H1, H2 from TOC
* inline images are kept inside page print margins
* tables wrap appropriately for page print margins
* print target is standard size (e.g., 8.5x11 or A4)
* grey or light color background for any code output for those
who do print to save on ink/toner
* open source font selections
* file name does not contain spaces or special characters
* Integrating building PDF jobs with current tox HTML build environment
* Applying PDF build functionalities to all HTML documents in
openstack-manuals repository
Project Scope
=============
* This spec mainly focuses on applying to documents in openstack-manuals
repository. security-doc and api-site are also good targets for building
PDFs, but they are out of scope in this spec.
* The support of building PDFs from translated documents is out of scope.
* For a basic PDF theme, the following requirements are out of scope.
* Index with page numbers
* OpenStack logo display on title page
(choosing which logo is appropriate for each deliverable would
get tedious)
* Optional: watermark to indicate draft or to which version
the document applies
Dependencies
============
* Can be dependent on pdf build program (e.g., LaTeX)
Testing
=======
* Testing of the tools will be done as part of the builds.
* Beta-reading period on PDF files and feedback will be helpful
for checking layout problems such as less image resolution and
table display problems.
References
==========
* http://lists.openstack.org/pipermail/openstack-docs/2016-July/008867.html
* http://lists.openstack.org/pipermail/openstack-docs/2016-July/008869.html
* https://review.openstack.org/#/c/396943/

106
specs/ocata/improve-ha-guide.rst
View File

@ -1,106 +0,0 @@
===================================
Improve the High Availability Guide
===================================
https://blueprints.launchpad.net/openstack-manuals/+spec/implement-ha-guide-todos
Problem description
===================
Presently, the High Availability (HA) Guide is incomplete. Information is
sparse and there are sections that have simply not been filled in.
The current guide is also out of date with regards to current best practices,
and it contains unnecessary information that should be removed.
Proposed change
===============
Firstly, reach consensus on the intended audience and high-level use cases
for the guide:
* As a cloud deployer, I need an OpenStack HA guide so that I can understand
both the architectural principles behind building an HA OpenStack cloud,
and the concrete steps involved in an implementation.
* As a cloud operator, I need an OpenStack HA guide so that I can understand
how an existing HA OpenStack cloud works and what is required for its
maintenance.
Based on that consensus, this spec proposes that the HA guide aims to define,
justify, and explain a high level architecture for a highly available setup
which uses the Pacemaker cluster manager to provide:
* Detection and recovery of machine and application-level failures
* Startup/shutdown ordering between applications
* Preferences for other applications that must/must-not run on the same
machine
* Provably correct response to any failure or cluster state
The guide will aim to stay relevant across all distributions whilst not
attempting to give every tiny detail about how to implement HA for each
distribution. It will also aim to avoid duplicating too much
information which can be found elsewhere. For example, basic package
installation for a given distribution.
Since the existing guide already has plenty of helpful and relevant
information, the proposal for this guide aims to avoid any rip-and-replace
action preferring instead incremental change.
Andrew Beekhof (specialty team lead) proposes to use the following document
as a reference providing updated information for the improved guide:
https://github.com/beekhof/osp-ha-deploy/blob/master/ha-openstack.md
.. note::
The above Github document contains heavy Red Hat content. Some may be
included in the final publication of the HA guide however it will be
structured such that advocates of other distributions/tools will be
able to easily add alternatives.
Alternatives
------------
* Leave the guide as is, and have the community slowly work at it over
time.
* Retire the guide, move relevant information to other guides and archive
it appropriately.
Implementation
==============
Assignee(s)
-----------
* Andrew Beekhof - beekhof
* Adam Spiers - aspiers
* Alexandra Settle - asettle
Work Items
----------
#. Go through HA guide bug list (see reference item 2) and remove what it out
of date, and deal with any bugs that are relevant and current.
#. Go through HA guide and delete outdated or irrelevant information.
#. Rearchitect the guide for new structure.
#. Introduce new content based on the above Github document, and SME content.
Dependencies
============
* Potentially dependent on community engagement and SMEs providing content.
Testing
=======
This document will be tested by the community as it is updated.
References
==========
#. Mailing list discussion, December 2016: http://lists.openstack.org/pipermail/openstack-docs/2016-December/009410.html
#. Growing list of relevant bugs: https://bugs.launchpad.net/openstack-manuals/+bugs?field.tag=ha-guide

96
specs/ocata/ops-guide-upgrades.rst
View File

@ -1,96 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
.. _ops-guide-upgrades:
=================================================
Operations Guide: Reference project upgrade notes
=================================================
https://blueprints.launchpad.net/openstack-manuals/+spec/ops-guide-upgrades
Problem description
===================
Service upgrade notes located in project repositories require greater
visibility for operators.
Proposed change
===============
Several project teams have produced upgrade notes in the developer
documentation that are beneficial to operators:
- `keystone <http://docs.openstack.org/developer/keystone/upgrading.html>`_
- `nova <http://docs.openstack.org/developer/nova/upgrade.html>`_ ,
- `cinder <https://review.openstack.org/#/c/393395/>`, and
- `neutron <http://docs.openstack.org/developer/neutron/devref/upgrade.html>`_
Due to a short development cycle for Ocata, the interim solution is to
provide links to this information in the Operations Guide to improve
visibility for operators. Links to other service upgrade notes will be added as
they become available.
There is a growing need to provide a project-based upgrade guide. During Ocata
development cycle, this can be discussed further, and give the opportunity for
other core project teams to discuss and document upgrade strategies. Then
potentially scope and plan a guide at the OpenStack Project Technical Group
meeting for the Pike release.
Alternatives
------------
* Leave as is.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* dazzachan
Other contributors:
* shilla-saebi
* alexandra-settle
Work items
----------
* Add links to keystone, nova, cinder, and neutron upgrade notes.
* Add links to other service upgrade notes when they become available.
* Update or remove outdated information in the Upgrades chapter.
* Liaise with SMEs to review content.
Dependencies
============
* Swift and glance project teams providing upgrade notes during the Ocata
development cycle.
Testing
=======
Testing will follow the standard documentation review process.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [ops-guide]
in the subject, monthly Ops Guide `specialty team meeting`_,
biweekly `documentation team meeting`_.
.. _`specialty team meeting`: https://wiki.openstack.org/wiki/Documentation/OpsGuide
.. _`documentation team meeting`: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting

105
specs/ocata/training-labs-python-port.rst
View File

@ -1,105 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=========================
Training-labs Python port
=========================
https://blueprints.launchpad.net/openstack-manuals/+spec/labs-python-port
Training labs was originally written in Bash. But it has grown from a simple
set of scripts to a full blown project. Moving to a modern interpreted
programming language is the next logical step. Hence, rewriting training-labs
in Python allows us to increase the agility, quality and features supported.
Python is an obvious choice. It is a programming language which should cater
the current demands, features while being the language of the OpenStack
community. Python is shipped by default on Mac OS X and Linux platforms.
Problem description
===================
Training labs is growing with ever increasing features and complexity. There
is a demand from users to add support for more features and plugins like
Public Cloud support. Moving to a modern programming language addresses
many inherent limitations of Bash for the given use-cases. The following
short comings, new feature demands are listed below which explain the need
for this rewrite.
* Adding new functionality like public cloud support (AWS, GCE, RackSpace).
* Providing better support for Windows platform.
* Using better configuration format.
* Supporting multiple architectures for OpenStack.
* Reducing the complexity for better testing, bug fixing, and more.
* Better support for new features like PXE booting.
* Providing proper modularity and abstraction for the host side scripts.
Proposed change
===============
Rewriting the host side scripts in Python. Host side scripts carry out tasks
to orchestrate the hypervisors (KVM/VirtualBox) and manage virtual networks,
provide logging, inject guest side scripts etc.
Initially, we plan to introduce Python scripts in parallel with existing Bash
scripts to eliminate the impact of this change to the end-users. Once the
Python port is tested, we will remove the host side Bash scripts. At this
point the end-users will invoke training-labs via Python. The impact to the
end-users is minimal to zero.
This is a major rewrite of the project and should impact the entire project
itself. But the migration plans provide a safe way to implement this change
and have minimal impact.
Alternatives
------------
* Use similar programming language like Ruby, Go Lang, etc.
* Improve the architecture and add relevant features to Bash.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Roger Luethi <rl@patchworkscience.org>
Other contributors:
Pranav Salunke <dguitarbite@gmail.com>
Work Items
----------
* Initial one to one rewrite to Python.
* Improve and refactor the python code.
* Remove older host side code (Bash code).
Dependencies
============
* None
Testing
=======
Mostly manual testing in the initial phases. During the latter part of the
implementation, the CI system should also carry out automated testing.
References
==========
None

83
specs/ocata/use-openstack-command.rst
View File

@ -1,83 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===============================================
Use openstack command to replace other commands
===============================================
https://blueprints.launchpad.net/openstack-manuals/+spec/use-openstack-command
Use the ``openstack`` command-line client to replace project specific commands
to promote consistency across the docs.
Problem description
===================
Docs historically use the individual command-line clients,
but we have the unified openstack CLIs at now, which deprecates
the individual CLIs. Therefore, we should use the ``openstack``
commands as possible.
Proposed change
===============
Use the ``openstack`` command-line client command to replace other commands
as possible as it is implemented.
Alternatives
------------
Leave the commands as they are.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* qiaomin032
Other contributors:
* caoyuan
Work Items
----------
* Use the ``openstack`` command to replace other commands.
Dependencies
============
None.
Testing
=======
Testing will follow the standard documentation review process.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with
in the subject, weekly Ops Guide `specialty team meeting`_,
weekly `documentation team meeting`_, and potentially etherpads.
.. _`specialty team meeting`:
https://wiki.openstack.org/wiki/Documentation
.. _`documentation team meeting`:
https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
* `Kilo operations midcycle meetup etherpad`_
.. _`Kilo operations midcycle meetup etherpad`:
https://etherpad.openstack.org/p/PAO-ops-ops-guide-fixing

177
specs/pike/admin-guide-repos.rst
View File

@ -1,177 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
========================
Distributed Admin Guides
========================
The growth of the number of OpenStack projects that are administered by an
operator base continues to grow. With growth and resource sharing in mind, we
want to ensure that the quality of an OpenStack administrator guide remains
high. To meet this goal, we think it's best to distribute the maintenance of
the source doc files within the project team's repositories.
This specification proposes allowing project teams to manage their
administrator guide content similar to how the api-ref and installation guides
are being managed.
Problem description
===================
Currently there are over sixty approved OpenStack projects. It is unreasonable
to expect the documentation team to maintain the administrator guide for all
of these projects. We need to optimize the usage of the documentation teams
resources.
Currently the administrator guide is in a separate git repository from the
code and patches being proposed. This leads to an "out of site, out of mind"
scenario where updates to the administrator guide are an afterthought if they
get updated at all.
Proposed change
===============
This specification proposes managing the administrator guide similar to the
installation guide, where the administrator guide contents are stored in the
project repository and are directly managed by the project team. The
documentation team can continue to provide an editorial role for the contents
of the administrator guide by posting patches to the guide contents in the
project repositories. This would allow for the continued consistent quality
and voice of the guide.
Existing administrator guide content would be migrated to the designated
project repositories. Project teams can decide which repository is appropriate
for the content, for example neutron may choose openstack/neutron-lib. Inside
these repositories the administrator guide content will be stored in a well
known and consistent location: admin-guide/source. The current administrator
guide is already laid out by service/project so this proposal should have
minimal impact to the look and feel of the guide.
Ownership of the project specific administrator guides is with the
respective project team, not the documentation team. This means the
content is in an existing or new repository owned by the project team,
reviews will be done by the project team, and bug reports will go in
the bug queue of the project.
The documentation team enables the project team to write the
project specific guides with mentoring, setting up needed
infrastructure, writing guidelines, provision of a template ("cookie
cutter"), and providing a working base administrator guide that the project
specific guides can use as reference.
The documentation team will select a list of priority projects for the release
series that will get a full review and scrub of the administrator guide
contents for those selected projects. This is similar to how the i18n team
prioritizes projects for localization.
To publish the project's administrator guide, the project will implement a tox
target to build the guide, similar to the one created for the installation
guides (see References). A gate job template 'admin-guide-jobs' will be added
to the project including the service name. This will cause the administration
guide to be published when updates are merged.
This publication mechanism should be similar that of the installation guide.
The administrator guide should be structured:
::
[openstack-docs/admin-guide/index.rst]
====================
Administrator Guides
====================
Compute service (nova)
======================
The Compute service ...
Installation is documented at
http://docs.openstack.org/project-admin-guide/pike/compute
Loadbalancer service (octavia)
======================
The Loadbalancer service ...
Installation is documented at
http://docs.openstack.org/project-admin-guide/pike/loadbalancer
.
[nova/admin-guide/source/index.rst]
=======
Compute
=======
* System architecture
* Images and instances
...
One difference with the administrator guide from the installation guide is
that all of the administrator guides are listed on one page. This makes it
easier for users to find any of the official OpenStack project administrator
guides.
With this change the administrator guide will now be versioned by release to
allow version specific content. This will be handled the same way the
installation guide is versioned. Administrator guides built from master will
be published to "draft" while stable branches will publish to the respective
release directory.
::
The master branch of octavia would publish to:
http://docs.openstack.org/project-admin-guide/draft/loadbalancer
The stable/pike branch of octavia would publish to:
http://docs.openstack.org/project-admin-guide/pike/loadbalancer
Alternatives
------------
1. Do nothing and attempt to maintain a centralized documentation repository.
2. Create a documentation repository for each project with shared core status.
3. Follow the proposed changes, but allow the documentation team core status.
Implementation
==============
Assignee(s)
-----------
Alexandra Settle (asettle)
Joseph Robinson (jrobinson)
Michael Johnson (johnsom)
Ildiko Vancsa (ildikov)
Brian Moss (Docs tools)
Entire documentation team
Work Items
----------
* Setup a wiki page to track the transition.
* Setup cookiecutter for the administrator guide.
* Encourage the project teams to move existing content to project team
repositories.
* Update the master index file to reflect the new structure.
* Write a base administrator guide.
* Setup gate jobs to publish the administrator guide on patch merge.
* Update the Documentation Contributor Guide to include the required steps
to setup a project administrator guide.
* Notify project teams when this method of publishing the project specific
administrator guide is available.
Dependencies
============
Testing
=======
References
==========
* https://etherpad.openstack.org/p/docs-i18n-ptg-pike-repos
* https://github.com/openstack/docs-specs/blob/master/specs/newton/project-specific-installguides.rst
* https://docs.openstack.org/contributor-guide/project-install-guide.html

159
specs/pike/arch-guide-restructure.rst
View File

@ -1,159 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=====================================
Architecture Design Guide Restructure
=====================================
Problem description
===================
The current Architecture Design Guide is primarily organized by use case
resulting in duplication of cloud architecture concepts.
The proposal is to revise the content structure to refine use cases to the
most common OpenStack deployments, and create an abstraction between
cloud architecture concepts and various OpenStack projects. This will make it
easier to maintain the guide.
Proposed change
===============
The proposed structure of the guide is to first describe common cloud use
cases, then general architectural concepts, followed by cloud architecture
design with a detailed breakdown of the major cloud components.
Proposed table of contents
--------------------------
The proposed structure for the updated Architecture Design Guide is as follows:
#. Overview
#. Use cases
#. Development cloud
#. General compute cloud
#. Web scale cloud
#. Storage cloud
#. Network Function Virtualization (NFV) cloud
#. High Availability
*Business requirements for implementing HA, what components in the
control plane need to be HA and why.*
#. Capacity planning and scaling
#. Adding cloud controller nodes
#. Segregating your cloud
#. Scalable hardware
#. Design
#. Compute
*Implementation of the compute platform including
hypervisors, nova, and ironic.*
#. Storage
*Storage choices and the implementation of
projects such as cinder and manila.*
#. Networking
*Networking design choices such as SDN, LBaaS,
and neutron.*
#. Identity
*Authentication, authorization, and assignment at
all levels for keystone and related projects.*
#. Image
*Management, creation, distribution, and
deployment of images for glance and related projects.*
#. Control Plane
*General implementation of the OpenStack control components and the
decision making that goes into the choices that need to be made.*
#. Dashboard and APIs
*Interaction with cloud services using a graphical interface or the
OpenStack APIs. This would include horizon and other Cloud Management
Platform (CMP) tools.*
The Use cases chapter will document the five most common OpenStack use cases.
It will describe the scope and requirements, which will be a precursor for
reference architecture information.
Alternatives
------------
Leave the guide as is.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
* dazzachan
Other contributors:
* tersian
* alexandra-settle
Work items
----------
* Remove the current Architecture Design Guide from docs.openstack.org, and
publish the draft Architecture Design Guide in its current state to
to increase visibility.
* Temporarily archive the current Architecture Design Guide in a directory
until the `docs archiving process
<https://specs.openstack.org/openstack/docs-specs/specs/pike/archiving.html>`
is implemented.
* Remove the Architecture chapter from the Operations Guide since the content
has been migrated to the draft Architecture Design Guide.
* Update ``.htaccess`` with redirects for removed/changed URLs.
* Complete writing the storage and networking sections in the
Design chapter, followed by the remaining sections.
* For each task, submit a bug report.
* Develop a use case content template to be applied to the Use Cases chapter.
Dependencies
============
Contributions and input from SMEs.
Testing
=======
Testing will follow the standard documentation review process.
References
==========
* Discussion can occur using any official medium including IRC in
#openstack-doc, the openstack-docs mailing list with [arch-guide]
in the subject heading, and `biweekly documentation team meeting
<https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting>`_.
* `Draft Architecture Design Guide <http://docs.openstack.org/draft/arch-design-draft/>`_
* `Work items <https://wiki.openstack.org/wiki/Architecture_Design_Guide_restructure_work_items>`_

130
specs/pike/consolidating-themes.rst
View File

@ -1,130 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===========================================
Consolidating OpenStack themes across sites
===========================================
Problem description
===================
When a reader comes to a page on docs.openstack.org, they may see one of two
themes styling the page: either oslosphinxtheme or openstackdocstheme. By
having two themes for a single subdomain, we do not provide a consistent
experience for visitors to the site. The navigation provided on the top and
side of each page varies with these two themes, and now that there is a new
logo for OpenStack itself, we would like to consolidate both themes into one
theme, openstackdocstheme.
Also, from a maintenance standpoint, by continuing to support two themes, we
must maintain and provide bug fixes for two Sphinx themes with limited web
development resources.
Proposed change
===============
Here's an overview of all the tasks needed to use a single theme consistently
across all documents built to docs.openstack.org.
Theme work:
Update openstackdocs theme to match the logo used on www.openstack.org.
User interface changes that must be provided in openstackdocstheme that do not
exist currently:
* Provide the version number of the built documentation in the footer of the
output. For example, "tempest 15.0.1.dev359 documentation" appears on each
page of the Tempest documentation. Currently, openstackdocstheme provides the
built date only, not the build version number.
* New logo that matches current logo used on www.openstack.org.
User interface differences that will not be ported from oslosphinx to
openstackdocstheme:
* Quick search form in bottom of left-hand navigation bar.
* Previous topic and Next topic shown in left-hand navigation bar.
* Return to project home page link in left-hand navigation bar.
* Customized list of links in header. For example, the page at
https://docs.openstack.org/infra/system-config/ contains a custom header.
* When a landing page like https://docs.openstack.org/infra/ uses oslosphinx,
the page should be redesigned with the new theme.
Configuration work:
Have all projects that build to the docs.openstack.org subdomain use the
openstackdocstheme theme instead of oslosphinx theme. Basically, update all
``conf.py`` files for documentation pages to use openstackdocstheme.
Make sure that the bug configuration is correct so that when a reader clicks
the "Log a bug" link in the built docs, the corresponding project's bug logging
location is opened.
Deprecate maintenance and use of the oslosphinx theme, addressing any unique
needs met by that theme within the openstackdocstheme.
Maintenance or project work:
Move any bugs in the backlog for oslosphinx theme to the openstack-doc-tools
bug queue at https://bugs.launchpad.net/openstack-doc-tools.
Alternatives
------------
Continue to use and maintain two themes, one for contributor documentation and
one for consumer documentation.
Alter oslosphinx theme to style all content like openstackdocstheme, basically
doing the opposite usage of themes proposed above. We could consider this
approach if it turns out that more ``conf.py`` files use the oslosphinx theme.
Implementation
==============
Assignee(s)
-----------
Work Items
----------
Communicate this spec to project teams.
Identify an Oslo liaison to help with any dependencies on reviews.
Ensure that the list of "lost" interface items is acceptable and that the list
itself is complete. If not, this spec and list should be modified.
Theme work listed above.
Configuration work listed above.
Maintenance work listed above.
Dependencies
============
Ensure other Oslo libraries do not have dependencies on the theme.
Testing
=======
Test that translations continue to work when using the openstackdocstheme for
all different types of content.
References
==========
* https://bugs.launchpad.net/openstack-doc-tools
* https://bugs.launchpad.net/oslo?field.searchtext=oslosphinx
* http://lists.openstack.org/pipermail/openstack-docs/2017-April/009893.html
* http://lists.openstack.org/pipermail/openstack-docs/2017-February/009752.html

100
specs/pike/document-tools.rst
View File

@ -1,100 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===================================================
Document openstack-doc-tools and openstackdocstheme
===================================================
https://blueprints.launchpad.net/openstack-doc-tools/+spec/document-tools
Problem description
===================
Documentation for `openstack-doc-tools
<http://git.openstack.org/cgit/openstack/openstack-doc-tools/>`_ and
`openstackdocstheme
<http://git.openstack.org/cgit/openstack/openstackdocstheme/>`_ is currently
divided between various README files in the project repositories and the
`OpenStack Documentation Contributor Guide
<https://docs.openstack.org/contributor-guide/index.html>`_. In some cases
content is duplicated, outdated, or missing.
Proposed change
===============
Create Sphinx documentation projects within the ``openstack-doc-tools`` and
``openstackdocstheme`` repositories, update and complete the documentation for
both repositories, then publish the guides to `docs.openstack.org/developer/
<https://docs.openstack.org/developer>`_.
Add appropriate links to the new guides from the **OpenStack Documentation
Contributor Guide** and the repository README files.
The ``openstack-doc-tools`` repository already has a Sphinx
documentation project that is not currently published but that can be used as
the basis for the guide.
``openstackdocstheme`` also has a Sphinx documentation project that provides
sample content for theme testing which should be retained or incorporated into
the published guide.
Alternatives
------------
- Consolidate the content into a new **OpenStack Documentation Tools Guide**
in the ``openstack-manuals`` repository.
- Consolidate the content into the existing **OpenStack Documentation
Contributor Guide**.
- Maintain the status quo (do nothing).
Implementation
==============
Assignee(s)
-----------
Primary assignee:
- Brian Moss (bmoss)
Other contributors:
- Documentation team
Work Items
----------
- Create Sphinx documentation projects within the ``openstack-doc-tools`` and
``openstackdocstheme`` repositories.
- Copy existing content into the new guides.
- Add doc checks to the tox environment and Jenkins gate.
- Publish the new guides to docs.openstack.org/developer/$REPO.
- Replace content in original locations with links to the content in the new
guides.
- Edit content and add missing material.
Dependencies
============
None
Testing
=======
Testing will follow the standard documentation review process.
References
==========
- `openstack-doc-tools <http://git.openstack.org/cgit/openstack/openstack-doc-tools/>`_
- `openstackdocstheme <http://git.openstack.org/cgit/openstack/openstackdocstheme/>`_
- `openstack-manuals <http://git.openstack.org/cgit/openstack/openstack-manuals>`_
- `OpenStack Documentation Contributor Guide <https://docs.openstack.org/contributor-guide/index.html>`_

394
specs/pike/os-manuals-migration.rst
View File

@ -1,394 +0,0 @@
===================================
OpenStack manuals project migration
===================================
Problem description
~~~~~~~~~~~~~~~~~~~
The documentation team are rapidly losing key contributors and core reviewers.
We are not alone, this is happening across the board. It is making things
harder, but not impossible.
Since our inception in 2010, we’ve been climbing higher and higher trying to
achieve the best documentation we could, and uphold our high standards.
However, we now need to take a step back and realise that the amount of work
we are attempting to maintain is out of reach for the team size that we have.
At the moment we have 13 cores, of whom none are full time contributors or
reviewers.
Until this point, the documentation team has owned several manuals that
include content related to multiple projects, including an installation
guide, admin guide, configuration guide, networking guide, and security
guide. Because the team no longer has the resources to own that content,
we want to invert the relationship between the doc team and project teams,
so that we become liaisons to help with maintenance instead of asking for
project teams to provide liaisons to help with content. As a part of that
change, we plan to move the existing content out of the central manuals
repository, into repositories owned by the appropriate project teams.
Project teams will then own the content and the documentation team will
assist by managing the build tools, helping with writing guidelines and
style, but not writing the bulk of the text.
We currently have the infrastructure set up to empower project teams to
manage their own documentation in their own tree, and many do. As part of
this change, the rest of the existing content from the install guide and
admin guide will also move into project-owned repositories.
Proposed change
~~~~~~~~~~~~~~~
Combine all of the documentation builds for a given repository, so
that each repository has a single doc/source directory, a single
sphinx conf.py, and a single job for building and publishing the
content including developer, contributor, and user documentation. This
option would reduce the number of build jobs we have to run, and cut
down on the number of separate sphinx configurations in each
repository.
Move most of the content from various guides in openstack-manuals into
the same repository as the thing being documented -- the documentation
should live with the code. For example, the installation instructions
for glance move to the glance repository and the reference for using
the glance client command line tool move to the python-glanceclient
repository.
In order to make it easy to include links from the landing pages on
docs.openstack.org, we need to ensure a minimum level of consistency
in the organization of the docs directory. The sections are based on
the existing high-level groupings for which there are already landing
pages on docs.openstack.org that will need to be updated. Within each
top-level directory, project teams are free to organize their content
however seems most appropriate to them. This is the proposed layout
for phase 1:
* ``doc/source/``
* ``install/`` -- anything having to do with installation of the
project
* ``contributor/`` -- anything related to contributing to the
project or how the team is managed. Applies to some of the current
content under /developer, we are changing the name to emphasize
that not all contributors are developers and sometimes developers
are users but not contributors. Service projects should place
their automatically generated class documentation under this part
of the tree, e.g. in ``contributor/api`` or
``contributor/internals``.
* ``configuration/`` -- automatically generated configuration
reference information based on oslo.config's sphinx integration
(or manually written for projects not using
oslo.config). Step-by-step guides for doing things like enabling
cells or configuring a specific driver should be placed in the
``admin/`` section.
* ``cli/`` -- command line tool reference docs, similar to man pages
These may be automatically generated with cliff's sphinx
integration, or manually written when auto-generation is not
possible. Tutorials or other step-by-step guides *using* these
tools should go in either the ``user/`` or ``admin/`` sections,
depending on their audience. Because the documentation for each
project should live in the repository with the code, this
directory may not be present for all service repositories but will
be present for most of the client library repositories.
* ``admin/`` -- any content from the old admin guide or anything
else that discusses how to run or operate the software
* ``user/`` -- end-user content such as concept guides, advice,
tutorials, step-by-step instructions for using the CLI to perform
specific tasks, etc.
* ``reference/`` -- any reference information associated with a
project that is not covered by one of the above categories.
Library projects should place their automatically generated class
documentation here.
This layout is the *minimum* set. Projects are free and encouraged to
add whatever other docs they need beyond this list, but these items
are listed here explicitly because there are already links to most of
them from landing pages, and landing pages can be created for the
others.
During a later phase, we will merge the API reference and release notes builds
into the same job, along with the rest of the documentation for a project.
Both of those builds have custom considerations, though, and it is more
important to move the content that is no longer going to be maintained
by the documentation team.
* ``doc/source/``
* ``api/`` -- the REST API reference and Guide content, when it exists
* ``releasenotes/`` -- reno directions (the actual release notes
inputs will stay in /releasenotes/notes, where they are now)
.. note::
Further discussion of the layout of the ``api/`` and
``releasenotes/`` directories is deferred until we are farther
along with the initial migration work.
A new documentation build job will be set up to take the output produced from
``tox -e venv -- python setup.py build_sphinx`` (matching the existing
`Consistent Testing Interface"
<https://governance.openstack.org/tc/reference/project-testing-interface.html>`_)
and publish it to a new location under `<http://docs.openstack.org>`_
The results will go to:
* ``docs.openstack.org/$project-name/latest`` -- build from master
* ``docs.openstack.org/$project-name/$series`` -- build from
stable/$series
* ``docs.openstack.org/$project-name/latest/$lang`` -- build
translated version from master
* ``docs.openstack.org/$project-name/$series/$lang`` -- build
translated version from stable/$series
Because we plan to reuse the existing `doc/source` directory in each project,
some of the existing content will need to be rearranged as part of importing
the content from openstack-manuals.
Ultimately, this changes the way we publish results, and redirects will be
required to be setup from all of the existing locations to the new locations,
and move all of the existing documentation under the new structure. We will
retain landing pages for the high level categories such as the install guides,
the configuration reference, and contributor documentation. Those pages will
continue to be maintained by the documentation team, and will deep-link into
the project team documentation.
For example, we will keep pages like
https://docs.openstack.org/project-install-guide/ocata/ but they will
provide lists of links to URLs like
https://docs.openstack.org/nova/ocata/install, which will be part of
the single doc build for nova.
What is happening to each guide?
--------------------------------
* Installation Guide
* Most of the content will move from openstack-manuals into each project
tree.
* The chapters not directly related to specific OpenStack projects,
such as the parts related to installing ntp and RabbitMQ, will be
retained in openstack-manuals in a shared guide for setting up
common dependencies so that content does not need to be reproduced
several times.
* The current guide is actually built 3 separate times, to cover 3
separate deployment platforms. The new build will not support
that, so the migration for the installation guide will involve
breaking the content up into separate pages for each platform (as
needed). Patch https://review.openstack.org/473579 splits the
content up into separate patches, one per OS.
* Project Installation guides, already in tree
* We recommend any installation guides already in-tree also move to the new
organization.
* Administrator Guide
* This content will move from openstack-manuals into each project tree. No
part will be retained in openstack-manuals. This spec was already
approved:
https://review.openstack.org/#/c/439122/
* High Availability Guide
* This guide will remain in openstack-manuals and be managed by the HA team.
For more information: https://blueprints.launchpad.net/openstack-manuals/+spec/implement-ha-guide-todos
* Operations Guide
* This guide will eventually move from openstack-manuals into the wiki.
Nothing will be done with it until a volunteer is found to manage that
move.
* Security Guide
* This content will stay in openstack-manuals, and be managed by the
security team.
* A notice is being added to indicate the last time it was updated
and which release is relevant
(https://review.openstack.org/#/c/470059).
* Architecture Design Guide
* This content will stay in openstack-manuals, and be deprecated.
* A notice will be added to each page indicating that the guide is up to
date as of $RELEASE after the finalisation of the current set of goals.
For more information on those goals:
https://blueprints.launchpad.net/openstack-manuals/+spec/arch-design-pike
* Networking Guide
* This content will move from openstack-manuals to the neutron repository
under docs/source/admin.
* Configuration Reference
* A few pages will move from openstack-manuals to the user-facing
documentation in oslo.config.
* The remainder will be removed, and replaced with new pages in the
in-tree documentation built using oslo_config.sphinxext.
* For tracking purposes, please see:
https://blueprints.launchpad.net/openstack-manuals/+spec/automate-config-ref
* API Documentation
* No changes.
* End User Guide
* This content will be divided between the horizon repository and
python-openstackclient repository.
* Command-Line Reference
* This content will move the project-specific client documentation
trees under doc/source/cli. For example, the information about
using the ``glance`` command line tool would move to the
python-glanceclient repository.
* Virtual Machine Image Reference
* This content will stay in openstack-manuals.
Migration process
-----------------
We will need to parallelize the migration work as much as possible if we are
going to complete it by the end of the Pike cycle. We will therefore need
project teams to find volunteers to "pull" the content into their
repositories, instead of having the documentation team "push" it.
.. note::
Use the topic ``doc-migration`` for all patches.
.. note::
Repeat these steps for all server projects, clients, and other
libraries.
#. Move the existing contributor-focused content to fit the layout
above. Submit that change with ``Depends-On:
Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454`` to tie it to this
spec.
#. If your project docs are not already building using
warning-is-error in setup.cfg, turn that on and fix any build
errors. Submit these as patches on top of the first patch.
#. Pull in the content being migrated, following the layout above.
* Go through the list of manuals in
https://etherpad.openstack.org/p/doc-migration-tracking and take
any actions needed to import content.
* Prepare one patch per manual (so one to import the install guide,
one to import the user guide, etc.). Submit these as patches on
top of any previous patches.
* `:term:` needs to be removed when importing and
performing the migration. This is due to the glossary remaining in the
openstack-manuals repo. Teams can choose to link to the glossary
on their own project pages if they so desire.
#. Ensure that there is an index.rst in each subdirectory of
doc/source so that the various landing pages managed by the
documentation team can link directly to that portion of the
documentation for your project. For example, in addition to moving
installation documentation into ``install/`` create
``install/index.rst`` with a ``toctree`` directive that shows all of
the installation.
#. Ensure that there is a top-level index.rst in doc/source that
incorporates all of the documentation for the project by including
all of the subdirectories in a toctree.
#. Update the theme for the in-tree docs to use the openstackdocstheme
instead of oslosphinx.
#. Add auto-generated config reference section(s) under the
``configuration/`` directory.
#. If pbr's autodoc feature is being used, update the ``api_doc_dir``
setting in the ``pbr`` section of ``setup.cfg`` to point to either
``reference/api`` (for libraries) or ``contributor/api`` (for other
types of projects).
#. Update project-config to have the doc build use the new jobs instead of the
old jobs by replacing 'openstack-server-publish-jobs' with
'openstack-unified-publish-jobs'.
Set ``Depends-On`` to the Change-Id from the patch created in
step 1. This ensures that we do not publish the old content to the
new location.
#. Add links to the reviews for individual TODO items below those
items in the sections dedicated to each manual. That way the docs
team will know when it is safe to start deleting content.
Alternatives
------------
#. We could retain the existing trees for developer and API docs, and add a new
one for "user" documentation. The installation guide, configuration guide,
and admin guide would move here for all projects. Neutron's user
documentation would include the current networking guide as well. This
option would add 1 new build to each repository, but would allow us to
easily roll
out the change with less disruption in the way the site is organized and
published, so there would be less work in the short term.
#. We could move the content under separate repositories owned by the project
teams, rather than in-tree with the code. This would allow project teams to
delegate management of the documentation to a separate review
project-sub-team, but would complicate the process of landing code and
documentation updates together so that the docs are always up to date.
#. Do nothing, and watch the world burn.
We did consider using "service type" instead of "project name" for the
publishing URLs, but not all of the projects that need documentations
are services. We will have user-facing documentation coming from several
Oslo libraries, for example.
Implementation
~~~~~~~~~~~~~~
Assignee(s)
-----------
Primary assignee:
* Alexandra Settle (asettle)
* Doug Hellmann (dhellmann)
* Project teams
* Documentation team PTL for Queens
* Documentation team
Work items
----------
The task list is quite long, so rather than repeat it here we give a summary.
There is more detail in the tracking pad mentioned in step 3.
#. Define new doc build and gate jobs that work like the current job, using
"tox -e venv -- python setup.py build_sphinx`" in a repository, but publish
to the new location of docs.o.o/$project-name/latest (dhellmann)
* https://review.openstack.org/#/c/471881/
#. Define doc build jobs for stable branches that run the same command but
publish to docs.o.o/$project-name/$series (dhellmann)
* The same job will work for all branches.
#. In parallel, in each repository, perform the migration steps listed above to
copy the new content into the doc/source directory. Refer to
https://etherpad.openstack.org/p/doc-migration-tracking for details about
which pages go into which project trees.
#. Define new translation jobs based on the ones for the release notes build
but using the main doc build.
#. Create a separate build for the openstack-manuals glossary.
Dependencies
~~~~~~~~~~~~
- Project team(s) collaboration
- Infra team assistance
- Reviews from multiple sources
References
~~~~~~~~~~
* https://etherpad.openstack.org/p/doc-planning
* The list of all URLs and where the content will move can be found
in: https://etherpad.openstack.org/p/doc-migration-tracking
* Documentation Publishing future thread:
http://lists.openstack.org/pipermail/openstack-dev/2017-May/117162.html
* Operations Guide Future thread:
http://lists.openstack.org/pipermail/openstack-dev/2017-June/117799.html

296
specs/queens/retention-policy.rst
View File

@ -1,296 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==============================================
Retention Policy for Published Documentation
==============================================
https://blueprints.launchpad.net/openstack-manuals/+spec/retention-policy
The `2017 User survey`_ highlights the fact that many of our users are
still deploying and otherwise working with versions of OpenStack for
which upstream support is no longer available. These end-of-life
versions are still clearly useful to some users, and to improve their
experience we should continue to make the documentation for those
releases available.
Problem description
===================
The current retention policy for published documentation calls for
manuals to be removed from docs.openstack.org when the associated
branches are marked "end of life" and closed. The older documentation
has been removed from the site in the past for several reasons. In no
particular order:
* **Content size**
The amount of content we were publishing was quite large for the
hosting service being used at the time.
* **Search results**
* Removing older documentation was seen as reducing confusion
because users searching without specifying a version number or
series name would not encounter information that was out of date.
* Documentation for older releases, by virtue of having longer lived
stable URLs, was appearing higher in search results than similar
updated content for newer releases.
* **Support requests**
Bugs and support requests have been filed for versions of the
documentation that will no longer be updated or fixed. This caused
undue burden to the documentation team.
* **Build support**
After the stable branch for the documentation was closed, there was
no longer a way to build and update the published
documentation. This is not an issue with regard to content, but we
have had at least one situation where there was a security issue for
a cross-site-scripting attack that pointed out if we had similar
problems in the future with dynamic aspects of the site for branches
that could no longer be built, deleting the content may be the only
action we could take. See commit
de6289854e9a059d5a33075b6593e7f9cb3b4f2d in the
clouddocs-maven-plugin repository for details (that repository is
not indexed via gerrit or available via the cgit web UI for some
reason).
We are updating this policy for two reasons:
1. According to the latest user survey at the time of this writing,
around 60% of users running a version of OpenStack no longer
supported upstream. These users are left without accurate
documentation for the versions of software that they are deploying.
2. As part of the :doc:`../pike/os-manuals-migration` initiative, more
of the actively maintained documentation is now managed by project
teams outside of the ``openstack-manuals`` git repository.
Proposed change
===============
The proposed change is to stop deleting all content from
docs.openstack.org based on its age, or the age of the software to
which it applies or the repository from which it was recovered.
We will also recover the admin guide, CLI reference, and user guide
for Mitaka through Ocata. The admin guide is meant to be reusable
between series, but that is only true when the underlying operating
system does not change. Since it has changed in the past, we need to
view the admin guide as series-specific *even when we do not change
it*. The CLI reference and user guide for Mitaka use the old versions
of the clients, and the options may have changed since then.
The Mitaka series was selected for several reasons.
1. It is the first series for which all of the documentation was
managed using Sphinx, which is easier to install than the older
tools and we have more knowledge throughout the community for
working with Sphinx.
2. It also represents a sufficiently old version to be useful to a
large number of users. The combination of utility and ease of
updating makes Mitaka a good compromise point for starting the new
retention policy.
3. Much of the project-specific documentation from the Mitaka release
still exists on docs.openstack.org so it will be easy to link to
it.
We will find other ways to mitigate the issues that motivated us to
adopt the old policy of deleting end-of-life releases.
The documentation for end-of-life releases will still be frozen when
the relevant stable branches are closed, so no updates will be
made. This change should not significantly expand the maintenance
burden or expectations of users.
* **Content size**
We have already migrated docs.openstack.org off of the CloudSites
hosting service to a standard web server with a large
filesystem. The amount of content we are publishing is no longer a
significant issue.
* **Search results**
Given the number of users running older versions, our priorities for
search results have changed. We *want* old versions to be available
via search engines, assuming the user can easily determine whether
the results they have found match their version or that they can
navigate between versions quickly.
We will continue to experiment with search engine optimization
techniques to have unqualified searches like "installing nova" show
newer results. That work will have its own spec, to be created by
the team that takes on the task.
We can make navigating between series-specific docs easy by taking
advantage of the ``earliest_published_series`` `configuration option
for the
theme. <https://docs.openstack.org/openstackdocstheme/latest/>`__
We will also update the documentation theme to include a watermark
or "badge" clearly indicating when content is considered old and
especially when it is no longer maintained. These markers need to be
built outside of the documentation itself so they can be updated
independently, without patching the docs or adding steps to the
stable branch EOL process. The plan discussed at the Queens PTG was
based on SVG files built from the openstack-manuals repository and
included into published pages by the ``openstackdocstheme``. More
details need to be worked out, and that work will involve its own
spec to follow this one.
* **Support requests**
Project teams are now responsible for project-specific
documentation. Bugs and support requests that come in to the
documentation team can be triaged and reassigned to project teams as
needed. Anything related to documentation that is no longer
supported should be treated the same way as bug reports for
unsupported code (closed "wontfix").
* **Build support**
Because we are not extending the supported lifetime for stable
branches and the documentation they contain, the only reasons to
need to build the docs are if we lose the data on the web server or
if there is another security issue. After a branch is closed, no
more updates to the documentation for that branch need to be
considered.
While we do not want to downplay the seriousness of potential issues
with cross-site scripting or JavaScript CVEs, we also do not want to
over-emphasize the likelihood of such issues coming up. If such
issues do arise, we will work on a resolution at that time. In a
worst-case scenario where restoring stable branches and changing the
builds does not work, and manual updates of the affected files are
not possible, we can delete the bad content. Any decision about the
best course of action will be made at the time by the people
actively working on the problem.
Similarly, if we experience a loss of data on the web server and
need to rebuild content, the people managing the recovery can
develop a plan when needed.
Alternatives
------------
#. Do nothing.
This option is not appealing because we have had clear and loud
requests from users to help them in this area.
#. Suggest that users build local copies of the documentation for old
releases.
Some users have resorted to trying to build their own internal
copies of the documentation to continue to manage their
deployments. They have found issues with the documentation at the
``$series-eol`` tags no longer building properly because external
references to things like sample files in git repositories are not
present.
#. Create ``docfixes`` branches, similar to the ``driverfixes``
branches used by project teams to allow vendors to collaborate on
patches to drivers after a version of the software has been marked
EOL. The ``docfixes`` branches would be allowed to build only the
documentation and update the published content on
docs.openstack.org (they would not be used for new releases of
software or code patches not related to documentation).
Without a significant number of contributors to review and manage
pages in these branches, it seems unlikely that we would see any
benefit from keeping them open. If the contributions to the
existing stable branches increase, we can reconsider this option in
the future.
#. Archive the content in non-indexed formats such as tarballs.
The old archival spec approved for Pike but never implemented
requires much more manual work and active management of old
content. Simply leaving the content in place on the web server is
more sustainable with a small documentation team.
Implementation
==============
Assignee(s)
-----------
Primary assignees:
* dhellmann
Other contributors:
* pkovar
Work Items
----------
* Restore the stable/mitaka version of the admin, CLI, and user guides
are published using series-specific URLs. (dhellmann)
* Create a new ``stable/mitaka`` branch.
* Update the build scripts so the manuals are published to
series-specific URLs.
* Add appropriate redirects.
* Re-close the branch.
* Update the stable/ocata branch of openstack/openstack-manuals to
build the admin, CLI, and user guides using series-specific
URLs. (*owner needed*)
* Update the build scripts so the manuals are published to
series-specific URLs.
* Add appropriate redirects.
* Update the stable/newton branch of openstack/openstack-manuals to
link to the Ocata versions of the admin, CLI, and user guides.
* Write a spec for the version "badges" and implement the appropriate
changes. (*owner needed*)
Dependencies
============
None
Testing
=======
Old documents will be recovered as-is, and only changes needed to
update the publication locations and ensure the builds work will be
allowed.
References
==========
* `2017 User survey`_
.. _2017 User survey: http://superuser.openstack.org/articles/2017-openstack-user-survey-insights/
* Mailing list threads
* `July 2017 (docs list)
<http://lists.openstack.org/pipermail/openstack-docs/2017-July/thread.html#10069>`__
* `July 2017 (dev list)
<http://lists.openstack.org/pipermail/openstack-dev/2017-July/thread.html#120254>`__
* `August 2017 (dev list)
<http://lists.openstack.org/pipermail/openstack-dev/2017-August/thread.html#120541>`__
* `Notes from discussion at the Queens PTG
<https://etherpad.openstack.org/p/docs-i18n-ptg-queens>`__
* `Old "Archiving" spec
<http://git.openstack.org/cgit/openstack/docs-specs/commit/?id=4ce480f4e29d8514a8b01acbe8157d84ed731d04>`__
* `Old "Archiving" blueprint
<https://blueprints.launchpad.net/openstack-manuals/+spec/archiving>`__

241
specs/rocky/front-page-template.rst
View File

@ -1,241 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==================================================
Front page template for project team documentation
==================================================
Use consistent content structure on the front page across all OpenStack
project team documentation hosted on docs.openstack.org.
Problem description
===================
Actionable feedback gathered at the `Queens PTG docs project meeting`_
included requests for the Documentation Project to provide guidance and a set
of recommendations on how to structure common content typically found on the
front page for project team docs, located at ``doc/source/index.rst`` in the
project team repository.
The goal of this change is to make it easier for users to find, navigate, and
consume project team documentation, and for contributors to set up and
maintain the project team documentation.
The recommended template as described in this spec would be included in the
`OpenStack Documentation Contributor Guide`_ as part of the project team setup
docs. The `Cookiecutter Template for new OpenStack projects`_ would also be
updated for changes described in this spec.
The recommendations for the project team front page would serve as the basis
for one of the future governance docs tags. Project teams would use the future
docs tag to show the maturity of their documentation and adherence to
community recommendations.
The definition of governance docs tags would be covered in a separate spec.
Proposed change
===============
The main idea behind the recommended content structure is to outline the
content based on target audience groups. The main audience groups are defined
as end users, operators, and contributors.
This template reuses some ideas from the front page of the `OpenStack Compute
service`_. Projects are encouraged to make additional changes to the template
per their specific needs so long as the design and structure ideas are
retained.
.. code-block:: rst
=================================================================
OpenStack {{service/component name}} ({{codename}}) documentation
=================================================================
.. figure:: images/project-logo.jpg
:alt: {{codename}} logo
:scale: 40%
:align: center
What is {{codename}}?
---------------------
{{codename}} is the OpenStack {{service/component name}} service/component
that does... to solve...
For end users
-------------
As an end user of {{codename}}, you want to... so that...
Using {{codename}}
~~~~~~~~~~~~~~~~~~
Contents:
.. toctree::
:maxdepth: 1
user/index
Using the {{codename}} API
~~~~~~~~~~~~~~~~~~~~~~~~~~
* `{{codename}} API <http://developer.openstack.org/api-ref/{{codename}}/>`_
For operators
-------------
As an operator of {{codename}}, you want to... so that...
Installing {{codename}}
~~~~~~~~~~~~~~~~~~~~~~~
Contents:
.. toctree::
:maxdepth: 1
install/index
Administrating {{codename}}
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Contents:
.. toctree::
:maxdepth: 1
admin/index
Reference
~~~~~~~~~
Contents:
.. toctree::
:maxdepth: 1
configuration/index
cli/index
Additional resources
~~~~~~~~~~~~~~~~~~~~
* `{{codename}} release notes <https://docs.openstack.org/releasenotes/{{codename}}/>`_
For contributors
----------------
As a contributor to {{codename}}, learn more about how to get started
as a contributor... and how to...
Getting started
~~~~~~~~~~~~~~~
* `OpenStack Contributor Guide <https://docs.openstack.org/contributors/>`_
Contributing to {{codename}}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Contents:
.. toctree::
:maxdepth: 1
contributor/index
Additional reference
~~~~~~~~~~~~~~~~~~~~
Contents:
.. toctree::
:maxdepth: 1
reference/index
Indices and tables
~~~~~~~~~~~~~~~~~~
Contents:
* :ref:`genindex`
* :ref:`modindex`
Search
------
* :ref:`search`
Alternatives
------------
#. Do nothing.
Essentially, maintain the status quo by not providing any guidance on
structuring content on the front page besides the ``doc/`` directory
structure as defined in `Project guide setup`_ in the OpenStack
Documentation Contributor Guide.
The status quo makes it more difficult for users to find, navigate, and
consume project team documentation, and for contributors to set up and
maintain the project team documentation.
#. Structure the front page based on current high-level groupings.
Consistently organize the content on front pages based on subdirectories in
the ``doc/`` directory of each project team repository, such as
``install/``, ``contributor/``, or ``configuration/``.
This might make it difficult for users to navigate the front page if there
are too many documents linked from that page.
Implementation
==============
Assignee(s)
-----------
* Petr Kovar (pkovar)
* Documentation team PTL for Stein
* Documentation team
* Project teams
Work items
----------
* Update the OpenStack Documentation Contributor Guide with the template.
* Update the Cookiecutter Template for new OpenStack projects with the
template.
* Project teams provide patches for their project team documentation to
implement the changes to the front page.
Dependencies
============
Get a buy-in and commitment from project teams and the OpenStack community
to actively implement the changes to project team documentation.
Testing
=======
Testing would follow the standard review process as defined by project teams.
References
==========
* `Project guide setup`_
* `Cookiecutter Template for new OpenStack projects`_
* `OpenStack Documentation Contributor Guide`_
* `Queens PTG docs project meeting`_
* :doc:`../pike/os-manuals-migration`
* `OpenStack Compute service`_
.. _Project guide setup: https://docs.openstack.org/doc-contrib-guide/project-guides.html
.. _Cookiecutter Template for new OpenStack projects: https://git.openstack.org/cgit/openstack-dev/cookiecutter/
.. _OpenStack Documentation Contributor Guide: https://docs.openstack.org/doc-contrib-guide/
.. _Queens PTG docs project meeting: https://etherpad.openstack.org/p/docs-i18n-ptg-rocky
.. _OpenStack Compute service: https://docs.openstack.org/nova/latest/

45
specs/skeleton.rst
View File

@ -1,45 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Title of your blueprint
==========================================
Problem description
===================
Proposed change
===============
Alternatives
------------
Implementation
==============
Assignee(s)
-----------
Work Items
----------
Dependencies
============
Testing
=======
References
==========

133
specs/template.rst
View File

@ -1,133 +0,0 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
Example Spec - The title of your blueprint
==========================================
Include the URL of your launchpad blueprint:
https://blueprints.launchpad.net/openstack-manuals/+spec/example
Introduction paragraph -- why are we doing anything? A single paragraph of
prose that operators can understand.
Some notes about using this template:
* Your spec should be in ReSTructured text, like this template.
* 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/openstack-manuals/+spec/awesome-doc
should be named awesome-doc.rst
* Please do not delete any of the sections in this template. If you have
nothing to say for a whole section, just write: None
* For help with syntax, see http://sphinx-doc.org/rest.html
* To test out your formatting, build the docs using tox, or see:
http://rst.ninjs.org
* If you would like to provide a diagram with your spec, ascii diagrams are
required. http://asciiflow.com/ is a very nice tool to assist with making
ascii diagrams. The reason for this is that the tool used to review specs is
based purely on plain text. Plain text will allow review to proceed without
having to look at additional files which can not be viewed in gerrit. It
will also allow inline feedback on the diagram itself.
Problem description
===================
A detailed description of the problem:
* For a new document, ensure you are clear about the
audience: End User vs Deployer
* For a major reworking of something existing it would describe the
problems in that document that are being addressed.
Proposed change
===============
Here is where you cover the change you propose to make in detail. How do you
propose to solve this problem?
If this is one part of a larger effort make it clear where this piece ends. In
other words, what's the scope of this effort?
Alternatives
------------
What other ways could we do this document? Why aren't we using those?
This doesn't have to be a full literature review, but it should
demonstrate that thought has been put into why the proposed solution
is an appropriate one.
Implementation
==============
Assignee(s)
-----------
Who is leading the writing of the code? Or is this a blueprint where you're
throwing it out there to see who picks it up?
If more than one person is working on the implementation, please designate the
primary author and contact.
Primary assignee:
<launchpad-id or None>
Other contributors:
<launchpad-id or None>
Work Items
----------
Work items or tasks -- break the feature up into the things that need to be
done to implement it. Those parts might end up being done by different people,
but we're mostly trying to understand the timeline for implementation.
Dependencies
============
* Include specific references to specs and/or blueprints in glance, or in other
projects, that this one either depends on or is related to.
* If this requires functionality of another project that is not currently used
by docs: document that fact.
* 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?
Testing
=======
Please discuss how the changed document will be tested.
References
==========
Please add any useful references here. You are not required to have any
reference. Moreover, this specification should still make sense when your
references are unavailable. Examples of what you could include are:
* Links to mailing list or IRC discussions
* Links to notes from a summit session
* Links to relevant research, if appropriate
* Related specifications as appropriate (e.g., if it's an EC2 thing, link the
EC2 docs)
* Anything else you feel it is worthwhile to refer to

0
tests/__init__.py
View File

106
tests/test_titles.py
View File

@ -1,106 +0,0 @@
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
import glob
import re
import docutils.core
import testtools
class TestTitles(testtools.TestCase):
def _get_title(self, section_tree):
section = {
'subtitles': [],
}
for node in section_tree:
if node.tagname == 'title':
section['name'] = node.rawsource
elif node.tagname == 'section':
subsection = self._get_title(node)
section['subtitles'].append(subsection['name'])
return section
def _get_titles(self, spec):
titles = {}
for node in spec:
if node.tagname == 'section':
# Note subsection subtitles are thrown away
section = self._get_title(node)
titles[section['name']] = section['subtitles']
return titles
def _check_titles(self, filename, expect, actual):
missing_sections = [x for x in expect.keys() if x not in actual.keys()]
extra_sections = [x for x in actual.keys() if x not in expect.keys()]
msgs = []
if len(missing_sections) > 0:
msgs.append("Missing sections: %s" % missing_sections)
if len(extra_sections) > 0:
msgs.append("Extra sections: %s" % extra_sections)
for section in expect.keys():
missing_subsections = [x for x in expect[section]
if x not in actual[section]]
# extra subsections are allowed
if len(missing_subsections) > 0:
msgs.append("Section '%s' is missing subsections: %s"
% (section, missing_subsections))
if len(msgs) > 0:
self.fail("While checking '%s':\n %s"
% (filename, "\n ".join(msgs)))
def _check_lines_wrapping(self, tpl, raw):
for i, line in enumerate(raw.split("\n")):
if "http://" in line or "https://" in line:
continue
self.assertTrue(
len(line) < 80,
msg="%s:%d: Line limited to a maximum of 79 characters." %
(tpl, i+1))
def _check_no_cr(self, tpl, raw):
matches = re.findall('\r', raw)
self.assertEqual(
len(matches), 0,
"Found %s literal carriage returns in file %s" %
(len(matches), tpl))
def _check_trailing_spaces(self, tpl, raw):
for i, line in enumerate(raw.split("\n")):
trailing_spaces = re.findall(" +$", line)
self.assertEqual(len(trailing_spaces),0,
"Found trailing spaces on line %s of %s" % (i+1, tpl))
def test_template(self):
with open('specs/template.rst') as f:
template = f.read()
spec = docutils.core.publish_doctree(template)
template_titles = self._get_titles(spec)
files = glob.glob('specs/*/*')
for filename in files:
self.assertTrue(filename.endswith(".rst"),
"spec's file must uses 'rst' extension.")
with open(filename) as f:
data = f.read()
spec = docutils.core.publish_doctree(data)
titles = self._get_titles(spec)
self._check_titles(filename, template_titles, titles)
self._check_lines_wrapping(filename, data)
self._check_no_cr(filename, data)
self._check_trailing_spaces(filename, data)

22
tox.ini
View File

@ -1,22 +0,0 @@
[tox]
minversion = 1.6
envlist = docs,py27
skipsdist = True
[testenv]
basepython = python3
usedevelop = True
setenv = VIRTUAL_ENV={envdir}
install_command = pip install -U {opts} {packages}
# The gate jobs run build_sphinx without using tox (thus ignore the
# docs target) and also call "tox -e py27", thus add doc8 here as
# default job.
commands = doc8 -e .rst specs/ doc/ README.rst
[testenv:venv]
commands = {posargs}
[testenv:docs]
commands =
doc8 -e .rst specs/ doc/ README.rst
sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html