Retire docs-specs
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:
parent
81abe0dfe2
commit
5a82d7e9a2
|
@ -1,18 +0,0 @@
|
||||||
.DS_Store
|
|
||||||
|
|
||||||
AUTHORS
|
|
||||||
ChangeLog
|
|
||||||
build
|
|
||||||
.tox
|
|
||||||
.venv
|
|
||||||
*.egg*
|
|
||||||
*.swp
|
|
||||||
*.swo
|
|
||||||
*.pyc
|
|
||||||
.testrepository
|
|
||||||
|
|
||||||
# Editors
|
|
||||||
*~
|
|
||||||
.*.swp
|
|
||||||
.bak
|
|
||||||
/.project
|
|
|
@ -1,9 +0,0 @@
|
||||||
- project:
|
|
||||||
templates:
|
|
||||||
- openstack-specs-jobs
|
|
||||||
check:
|
|
||||||
jobs:
|
|
||||||
- openstack-tox-py27
|
|
||||||
gate:
|
|
||||||
jobs:
|
|
||||||
- openstack-tox-py27
|
|
3
LICENSE
3
LICENSE
|
@ -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
67
README.rst
|
@ -1,62 +1,9 @@
|
||||||
========================
|
This project is no longer maintained.
|
||||||
Team and repository tags
|
|
||||||
========================
|
|
||||||
|
|
||||||
.. image:: https://governance.openstack.org/tc/badges/docs-specs.svg
|
The contents of this repository are still available in the Git
|
||||||
:target: https://governance.openstack.org/tc/reference/tags/index.html
|
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
|
For any further questions, please email
|
||||||
|
openstack-discuss@lists.openstack.org.
|
||||||
======================================
|
|
||||||
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/.
|
|
||||||
|
|
|
@ -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
|
|
|
@ -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 +0,0 @@
|
||||||
.. include:: ../../README.rst
|
|
|
@ -1 +0,0 @@
|
||||||
../../specs
|
|
|
@ -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
28
setup.cfg
|
@ -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
29
setup.py
|
@ -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)
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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/
|
|
|
@ -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
|
|
|
@ -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>`_
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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/>`_
|
|
|
@ -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
|
|
|
@ -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.
|
|
|
@ -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
|
|
|
@ -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.
|
|
|
@ -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
|
|
||||||
|
|
|
@ -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
|
|
||||||
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
||||||
|
|
|
@ -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/
|
|
|
@ -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
|
|
||||||
|
|
|
@ -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
|
|
||||||
|
|
|
@ -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
|
|
||||||
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
||||||
|
|
|
@ -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
|
|
||||||
|
|
||||||
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
||||||
|
|
|
@ -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
|
|
|
@ -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
|
|
||||||
|
|
|
@ -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
|
|
|
@ -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
|
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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 _
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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/
|
|
|
@ -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>`_.
|
|
|
@ -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
|
|
|
@ -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
|
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -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>`_.
|
|
||||||
|
|
|
@ -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
|
|
||||||
|
|
|
@ -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
|
|
|
@ -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/
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
|
@ -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
|
|
||||||
|
|
||||||
|
|
|
@ -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
|
|
|
@ -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>`_
|
|
|
@ -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
|
|
|
@ -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>`_
|
|
|
@ -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
|
|
|
@ -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>`__
|
|
|
@ -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/
|
|
|
@ -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
|
|
||||||
==========
|
|
||||||
|
|
||||||
|
|
|
@ -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
|
|
|
@ -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
22
tox.ini
|
@ -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
|
|
Loading…
Reference in New Issue