diff --git a/.gitignore b/.gitignore deleted file mode 100644 index a310ca9..0000000 --- a/.gitignore +++ /dev/null @@ -1,18 +0,0 @@ -.DS_Store - -AUTHORS -ChangeLog -build -.tox -.venv -*.egg* -*.swp -*.swo -*.pyc -.testrepository - -# Editors -*~ -.*.swp -.bak -/.project diff --git a/.zuul.yaml b/.zuul.yaml deleted file mode 100644 index f3848fb..0000000 --- a/.zuul.yaml +++ /dev/null @@ -1,9 +0,0 @@ -- project: - templates: - - openstack-specs-jobs - check: - jobs: - - openstack-tox-py27 - gate: - jobs: - - openstack-tox-py27 diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 75a29c4..0000000 --- a/LICENSE +++ /dev/null @@ -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 diff --git a/README.rst b/README.rst index a57f375..eb99bcd 100644 --- a/README.rst +++ b/README.rst @@ -1,62 +1,9 @@ -======================== -Team and repository tags -======================== +This project is no longer maintained. -.. image:: https://governance.openstack.org/tc/badges/docs-specs.svg - :target: https://governance.openstack.org/tc/reference/tags/index.html +The contents of this repository are still available in the Git +source code management system. To see the contents of this +repository before it reached its end of life, please check out the +previous commit with "git checkout HEAD^1". -.. Change things from this point on - -====================================== -OpenStack Documentation Specifications -====================================== - -This git repository is used to hold approved design specifications for -additions to the OpenStack Documentation program. Reviews of the specs -are done in gerrit, using a similar workflow to how we review and -merge changes to the docs and supporting tools. - -The layout of this repository is:: - - specs// - -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/` 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 `_. - -Please note, Launchpad blueprints are still used for tracking the -current status of blueprints. For more information, see -https://wiki.openstack.org/wiki/Blueprints. - -For more information about working with gerrit, see -https://docs.openstack.org/infra/manual/developers.html#development-workflow. - -To validate that the specification is syntactically correct (i.e. get more -confidence in the Zuul result), please execute the following command:: - - $ tox - -After running ``tox``, the documentation will be available for viewing in HTML -format in the ``doc/build/`` directory. Please do not check in the generated -HTML files as a part of your commit. - -The files are published at https://specs.openstack.org/openstack/docs-specs. - -The git repository is located at -https://git.openstack.org/cgit/openstack/docs-specs/. +For any further questions, please email +openstack-discuss@lists.openstack.org. diff --git a/doc/source/conf.py b/doc/source/conf.py deleted file mode 100644 index a125627..0000000 --- a/doc/source/conf.py +++ /dev/null @@ -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 -# " v 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 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 diff --git a/doc/source/index.rst b/doc/source/index.rst deleted file mode 100644 index f3b6722..0000000 --- a/doc/source/index.rst +++ /dev/null @@ -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 - -================== -Indices and tables -================== - -* :ref:`search` diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3..0000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst diff --git a/doc/source/specs b/doc/source/specs deleted file mode 120000 index 87a4030..0000000 --- a/doc/source/specs +++ /dev/null @@ -1 +0,0 @@ -../../specs \ No newline at end of file diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 375b6cb..0000000 --- a/requirements.txt +++ /dev/null @@ -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 diff --git a/setup.cfg b/setup.cfg deleted file mode 100644 index 8e3313c..0000000 --- a/setup.cfg +++ /dev/null @@ -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 diff --git a/setup.py b/setup.py deleted file mode 100644 index 3887303..0000000 --- a/setup.py +++ /dev/null @@ -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) diff --git a/specs/juno/common-glossary-setup.rst b/specs/juno/common-glossary-setup.rst deleted file mode 100644 index 17f1167..0000000 --- a/specs/juno/common-glossary-setup.rst +++ /dev/null @@ -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 diff --git a/specs/juno/create-networking-guide.rst b/specs/juno/create-networking-guide.rst deleted file mode 100644 index 2838b15..0000000 --- a/specs/juno/create-networking-guide.rst +++ /dev/null @@ -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 diff --git a/specs/juno/heat-templates.rst b/specs/juno/heat-templates.rst deleted file mode 100644 index 5f0903f..0000000 --- a/specs/juno/heat-templates.rst +++ /dev/null @@ -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 diff --git a/specs/kilo/draft-publishing.rst b/specs/kilo/draft-publishing.rst deleted file mode 100644 index 39e9294..0000000 --- a/specs/kilo/draft-publishing.rst +++ /dev/null @@ -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 diff --git a/specs/kilo/installguide-kilo.rst b/specs/kilo/installguide-kilo.rst deleted file mode 100644 index eaf09e4..0000000 --- a/specs/kilo/installguide-kilo.rst +++ /dev/null @@ -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 diff --git a/specs/kilo/migrate-to-new-web-design.rst b/specs/kilo/migrate-to-new-web-design.rst deleted file mode 100644 index b84212f..0000000 --- a/specs/kilo/migrate-to-new-web-design.rst +++ /dev/null @@ -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 `_ -* `Content view `_ -* `Search results `_ -* `Example language landing page `_ - -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 -`_ 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 -`_ -(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/ diff --git a/specs/kilo/move-driver-docs.rst b/specs/kilo/move-driver-docs.rst deleted file mode 100644 index 6a2b2fd..0000000 --- a/specs/kilo/move-driver-docs.rst +++ /dev/null @@ -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 -`_ 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 diff --git a/specs/kilo/openstack-firstapp.rst b/specs/kilo/openstack-firstapp.rst deleted file mode 100644 index d499c04..0000000 --- a/specs/kilo/openstack-firstapp.rst +++ /dev/null @@ -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 `_. - -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 `_ - -* `Application Eco WG - meeting - "first app tutorial" `_ diff --git a/specs/kilo/training-guides-icehouse-release.rst b/specs/kilo/training-guides-icehouse-release.rst deleted file mode 100644 index 9c30454..0000000 --- a/specs/kilo/training-guides-icehouse-release.rst +++ /dev/null @@ -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 diff --git a/specs/kilo/training-guides-osbash-color.rst b/specs/kilo/training-guides-osbash-color.rst deleted file mode 100644 index 71a94d7..0000000 --- a/specs/kilo/training-guides-osbash-color.rst +++ /dev/null @@ -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 diff --git a/specs/liberty/api-site.rst b/specs/liberty/api-site.rst deleted file mode 100644 index 2b8face..0000000 --- a/specs/liberty/api-site.rst +++ /dev/null @@ -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 -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 `_: - -* 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 `_ - which has been run on our current WADL files. The `resulting Swagger files `_ 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 `_ -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/. - -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 diff --git a/specs/liberty/arch-guide.rst b/specs/liberty/arch-guide.rst deleted file mode 100644 index c24c5ce..0000000 --- a/specs/liberty/arch-guide.rst +++ /dev/null @@ -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 `_ - -`Swarm Website `_ diff --git a/specs/liberty/audio-visual.rst b/specs/liberty/audio-visual.rst deleted file mode 100644 index 54a6277..0000000 --- a/specs/liberty/audio-visual.rst +++ /dev/null @@ -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 - `_) -* Scripts will be reviewed by team -* After approval, videos will be created -* Videos will be hosted on the `training-guides channel on YouTube - `_ - -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 diff --git a/specs/liberty/docs-contributor-guide.rst b/specs/liberty/docs-contributor-guide.rst deleted file mode 100644 index 08578eb..0000000 --- a/specs/liberty/docs-contributor-guide.rst +++ /dev/null @@ -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 `_ - - - 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 `_ - - - 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 `_ - and `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 `_ - - - 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 - `_ - - - 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 `_ - - - 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 `_ - - - As a docs contributor, I would like to be aware of how to name and - arrange files and directories in books. - - -.. note:: `HowTo `_ - and `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 `_ - -Other contributors: - -* Alexander Adamov, `aadamov `_ - -* Olena Logvinova, `ologvinova `_ - -* Maria Zlatkova, `mzlatkova `_ - - -Testing -======= - -Feedback from the docs contributors - - -References -========== - -* Add the link to the project wiki page. diff --git a/specs/liberty/ha-guide.rst b/specs/liberty/ha-guide.rst deleted file mode 100644 index 302ba41..0000000 --- a/specs/liberty/ha-guide.rst +++ /dev/null @@ -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 -`__ -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 -`__ 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: - - -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 diff --git a/specs/liberty/installguide-liberty-debian.rst b/specs/liberty/installguide-liberty-debian.rst deleted file mode 100644 index f58937e..0000000 --- a/specs/liberty/installguide-liberty-debian.rst +++ /dev/null @@ -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 -`_ - -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 -`_, -weekly `documentation team meeting -`_, -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. diff --git a/specs/liberty/installguide-liberty-rst.rst b/specs/liberty/installguide-liberty-rst.rst deleted file mode 100644 index d5c9eb0..0000000 --- a/specs/liberty/installguide-liberty-rst.rst +++ /dev/null @@ -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 - diff --git a/specs/liberty/installguide-liberty.rst b/specs/liberty/installguide-liberty.rst deleted file mode 100644 index 9d3d968..0000000 --- a/specs/liberty/installguide-liberty.rst +++ /dev/null @@ -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 - diff --git a/specs/liberty/manila-config-ref.rst b/specs/liberty/manila-config-ref.rst deleted file mode 100644 index eb9248c..0000000 --- a/specs/liberty/manila-config-ref.rst +++ /dev/null @@ -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 diff --git a/specs/liberty/reorganise-user-guides.rst b/specs/liberty/reorganise-user-guides.rst deleted file mode 100644 index eef2c5d..0000000 --- a/specs/liberty/reorganise-user-guides.rst +++ /dev/null @@ -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 diff --git a/specs/liberty/training-labs.rst b/specs/liberty/training-labs.rst deleted file mode 100644 index 90daf8d..0000000 --- a/specs/liberty/training-labs.rst +++ /dev/null @@ -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 - diff --git a/specs/mitaka/app-guides-mitaka-vision.rst b/specs/mitaka/app-guides-mitaka-vision.rst deleted file mode 100644 index 7094115..0000000 --- a/specs/mitaka/app-guides-mitaka-vision.rst +++ /dev/null @@ -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/ diff --git a/specs/mitaka/archguide-mitaka-reorg.rst b/specs/mitaka/archguide-mitaka-reorg.rst deleted file mode 100644 index b6d0cc8..0000000 --- a/specs/mitaka/archguide-mitaka-reorg.rst +++ /dev/null @@ -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 - diff --git a/specs/mitaka/archguide-mitaka-rst.rst b/specs/mitaka/archguide-mitaka-rst.rst deleted file mode 100644 index 754bafc..0000000 --- a/specs/mitaka/archguide-mitaka-rst.rst +++ /dev/null @@ -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 - diff --git a/specs/mitaka/cli-ref-rst.rst b/specs/mitaka/cli-ref-rst.rst deleted file mode 100644 index 769816e..0000000 --- a/specs/mitaka/cli-ref-rst.rst +++ /dev/null @@ -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 - diff --git a/specs/mitaka/config-ref-common-options.rst b/specs/mitaka/config-ref-common-options.rst deleted file mode 100644 index 189e212..0000000 --- a/specs/mitaka/config-ref-common-options.rst +++ /dev/null @@ -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 diff --git a/specs/mitaka/config-ref-rst.rst b/specs/mitaka/config-ref-rst.rst deleted file mode 100644 index c4946b6..0000000 --- a/specs/mitaka/config-ref-rst.rst +++ /dev/null @@ -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 diff --git a/specs/mitaka/create-manila-install-guide.rst b/specs/mitaka/create-manila-install-guide.rst deleted file mode 100644 index a85c110..0000000 --- a/specs/mitaka/create-manila-install-guide.rst +++ /dev/null @@ -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 `__ -- `Manila user guide `__ -- `Manila configuration reference `__ - -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 diff --git a/specs/mitaka/image-guide-rst.rst b/specs/mitaka/image-guide-rst.rst deleted file mode 100644 index 1399678..0000000 --- a/specs/mitaka/image-guide-rst.rst +++ /dev/null @@ -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 - diff --git a/specs/mitaka/improve-ops-guide.rst b/specs/mitaka/improve-ops-guide.rst deleted file mode 100644 index fa258a1..0000000 --- a/specs/mitaka/improve-ops-guide.rst +++ /dev/null @@ -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 - - diff --git a/specs/mitaka/installguide-mitaka.rst b/specs/mitaka/installguide-mitaka.rst deleted file mode 100644 index 516e24b..0000000 --- a/specs/mitaka/installguide-mitaka.rst +++ /dev/null @@ -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 diff --git a/specs/mitaka/networkguide-ovn.rst b/specs/mitaka/networkguide-ovn.rst deleted file mode 100644 index b9c0ed3..0000000 --- a/specs/mitaka/networkguide-ovn.rst +++ /dev/null @@ -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 diff --git a/specs/mitaka/networkguide-versioning.rst b/specs/mitaka/networkguide-versioning.rst deleted file mode 100644 index af034fa..0000000 --- a/specs/mitaka/networkguide-versioning.rst +++ /dev/null @@ -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 diff --git a/specs/mitaka/ops-guide-rst.rst b/specs/mitaka/ops-guide-rst.rst deleted file mode 100644 index 714ae61..0000000 --- a/specs/mitaka/ops-guide-rst.rst +++ /dev/null @@ -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 - diff --git a/specs/mitaka/publish-stable-translation.rst b/specs/mitaka/publish-stable-translation.rst deleted file mode 100644 index c4a3b6f..0000000 --- a/specs/mitaka/publish-stable-translation.rst +++ /dev/null @@ -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 diff --git a/specs/mitaka/review-docimpact.rst b/specs/mitaka/review-docimpact.rst deleted file mode 100644 index f4f1d2a..0000000 --- a/specs/mitaka/review-docimpact.rst +++ /dev/null @@ -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 - diff --git a/specs/mitaka/trove-install-section.rst b/specs/mitaka/trove-install-section.rst deleted file mode 100644 index 3900b07..0000000 --- a/specs/mitaka/trove-install-section.rst +++ /dev/null @@ -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 `__ -- `trove user guide cmd line `__ -- `trove user guide dashboard `__ -- `trove configuration reference `__ -- `trove API reference `__ - -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 diff --git a/specs/mitaka/ui-content-guidelines.rst b/specs/mitaka/ui-content-guidelines.rst deleted file mode 100644 index aaf8e4c..0000000 --- a/specs/mitaka/ui-content-guidelines.rst +++ /dev/null @@ -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 - - - diff --git a/specs/mitaka/upgrades.rst b/specs/mitaka/upgrades.rst deleted file mode 100644 index 27def31..0000000 --- a/specs/mitaka/upgrades.rst +++ /dev/null @@ -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 diff --git a/specs/mitaka/user-guides-mitaka-reorg.rst b/specs/mitaka/user-guides-mitaka-reorg.rst deleted file mode 100644 index 0fab701..0000000 --- a/specs/mitaka/user-guides-mitaka-reorg.rst +++ /dev/null @@ -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 diff --git a/specs/mitaka/zaqar-config-ref.rst b/specs/mitaka/zaqar-config-ref.rst deleted file mode 100644 index 1957d7b..0000000 --- a/specs/mitaka/zaqar-config-ref.rst +++ /dev/null @@ -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 diff --git a/specs/newton/arch-guide-restructure.rst b/specs/newton/arch-guide-restructure.rst deleted file mode 100644 index 8fc6b6a..0000000 --- a/specs/newton/arch-guide-restructure.rst +++ /dev/null @@ -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 diff --git a/specs/newton/consistency-file-rename.rst b/specs/newton/consistency-file-rename.rst deleted file mode 100644 index 9fa87d7..0000000 --- a/specs/newton/consistency-file-rename.rst +++ /dev/null @@ -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 _ diff --git a/specs/newton/contributor-guide-release-chapter.rst b/specs/newton/contributor-guide-release-chapter.rst deleted file mode 100644 index 48db25f..0000000 --- a/specs/newton/contributor-guide-release-chapter.rst +++ /dev/null @@ -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 diff --git a/specs/newton/contributor-guide-reorg.rst b/specs/newton/contributor-guide-reorg.rst deleted file mode 100644 index 9f04f17..0000000 --- a/specs/newton/contributor-guide-reorg.rst +++ /dev/null @@ -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 diff --git a/specs/newton/docbook-removal.rst b/specs/newton/docbook-removal.rst deleted file mode 100644 index a782b73..0000000 --- a/specs/newton/docbook-removal.rst +++ /dev/null @@ -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 diff --git a/specs/newton/improve-glossary-usage.rst b/specs/newton/improve-glossary-usage.rst deleted file mode 100644 index 8a11691..0000000 --- a/specs/newton/improve-glossary-usage.rst +++ /dev/null @@ -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 diff --git a/specs/newton/installguide.rst b/specs/newton/installguide.rst deleted file mode 100644 index b3fc953..0000000 --- a/specs/newton/installguide.rst +++ /dev/null @@ -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 -`__ -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 diff --git a/specs/newton/project-specific-installguides.rst b/specs/newton/project-specific-installguides.rst deleted file mode 100644 index b5e0eac..0000000 --- a/specs/newton/project-specific-installguides.rst +++ /dev/null @@ -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 -`__ -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 - `__. - -* 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 - `_ - (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/ diff --git a/specs/newton/release-notes-guidelines-to-cg.rst b/specs/newton/release-notes-guidelines-to-cg.rst deleted file mode 100644 index 3bf4b91..0000000 --- a/specs/newton/release-notes-guidelines-to-cg.rst +++ /dev/null @@ -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 `_, -`Infra manual `_, -or `Reno documentation `_. - -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 - -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 `__ - * `Reno documentation `_ - * `Infra manual `_ - -* 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 `_. -* `Reno documentation `_. -* Current instructions for the developers - `Managing Release Notes `_. diff --git a/specs/newton/training-labs-pxe-server.rst b/specs/newton/training-labs-pxe-server.rst deleted file mode 100644 index 0b3df84..0000000 --- a/specs/newton/training-labs-pxe-server.rst +++ /dev/null @@ -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 diff --git a/specs/newton/ui-heuristic-checklist.rst b/specs/newton/ui-heuristic-checklist.rst deleted file mode 100644 index 4d011da..0000000 --- a/specs/newton/ui-heuristic-checklist.rst +++ /dev/null @@ -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 - - - diff --git a/specs/newton/user-guide-edit.rst b/specs/newton/user-guide-edit.rst deleted file mode 100644 index e7936ad..0000000 --- a/specs/newton/user-guide-edit.rst +++ /dev/null @@ -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 `_. - diff --git a/specs/newton/ux-personas.rst b/specs/newton/ux-personas.rst deleted file mode 100644 index c9f27cf..0000000 --- a/specs/newton/ux-personas.rst +++ /dev/null @@ -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 - diff --git a/specs/ocata/arch-guide-restructure.rst b/specs/ocata/arch-guide-restructure.rst deleted file mode 100644 index 10b9ddf..0000000 --- a/specs/ocata/arch-guide-restructure.rst +++ /dev/null @@ -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 `_ - -* `Etherpad `_ - -.. _`Ops/arch tasks etherpad`: https://etherpad.openstack.org/p/ops-arch-tasks diff --git a/specs/ocata/build-pdf-from-rst-guides.rst b/specs/ocata/build-pdf-from-rst-guides.rst deleted file mode 100644 index b46fa6d..0000000 --- a/specs/ocata/build-pdf-from-rst-guides.rst +++ /dev/null @@ -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/ diff --git a/specs/ocata/improve-ha-guide.rst b/specs/ocata/improve-ha-guide.rst deleted file mode 100644 index 3560bf1..0000000 --- a/specs/ocata/improve-ha-guide.rst +++ /dev/null @@ -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 diff --git a/specs/ocata/ops-guide-upgrades.rst b/specs/ocata/ops-guide-upgrades.rst deleted file mode 100644 index 9707e22..0000000 --- a/specs/ocata/ops-guide-upgrades.rst +++ /dev/null @@ -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 `_ -- `nova `_ , -- `cinder `, and -- `neutron `_ - -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 diff --git a/specs/ocata/training-labs-python-port.rst b/specs/ocata/training-labs-python-port.rst deleted file mode 100644 index 4a8f185..0000000 --- a/specs/ocata/training-labs-python-port.rst +++ /dev/null @@ -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 - -Other contributors: - Pranav Salunke - -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 diff --git a/specs/ocata/use-openstack-command.rst b/specs/ocata/use-openstack-command.rst deleted file mode 100644 index e3fad4f..0000000 --- a/specs/ocata/use-openstack-command.rst +++ /dev/null @@ -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 - - diff --git a/specs/pike/admin-guide-repos.rst b/specs/pike/admin-guide-repos.rst deleted file mode 100644 index 9e63226..0000000 --- a/specs/pike/admin-guide-repos.rst +++ /dev/null @@ -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 diff --git a/specs/pike/arch-guide-restructure.rst b/specs/pike/arch-guide-restructure.rst deleted file mode 100644 index 893cbd6..0000000 --- a/specs/pike/arch-guide-restructure.rst +++ /dev/null @@ -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 - ` - 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 - `_. - -* `Draft Architecture Design Guide `_ - -* `Work items `_ diff --git a/specs/pike/consolidating-themes.rst b/specs/pike/consolidating-themes.rst deleted file mode 100644 index 09fc781..0000000 --- a/specs/pike/consolidating-themes.rst +++ /dev/null @@ -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 diff --git a/specs/pike/document-tools.rst b/specs/pike/document-tools.rst deleted file mode 100644 index a2d1af1..0000000 --- a/specs/pike/document-tools.rst +++ /dev/null @@ -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 -`_ and -`openstackdocstheme -`_ is currently -divided between various README files in the project repositories and the -`OpenStack Documentation Contributor Guide -`_. 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/ -`_. - -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 `_ -- `openstackdocstheme `_ -- `openstack-manuals `_ -- `OpenStack Documentation Contributor Guide `_ diff --git a/specs/pike/os-manuals-migration.rst b/specs/pike/os-manuals-migration.rst deleted file mode 100644 index 8f6b70f..0000000 --- a/specs/pike/os-manuals-migration.rst +++ /dev/null @@ -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" -`_) -and publish it to a new location under ``_ -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 diff --git a/specs/queens/retention-policy.rst b/specs/queens/retention-policy.rst deleted file mode 100644 index 10f738a..0000000 --- a/specs/queens/retention-policy.rst +++ /dev/null @@ -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. `__ - - 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) - `__ - * `July 2017 (dev list) - `__ - * `August 2017 (dev list) - `__ - -* `Notes from discussion at the Queens PTG - `__ - -* `Old "Archiving" spec - `__ - -* `Old "Archiving" blueprint - `__ diff --git a/specs/rocky/front-page-template.rst b/specs/rocky/front-page-template.rst deleted file mode 100644 index 210bc72..0000000 --- a/specs/rocky/front-page-template.rst +++ /dev/null @@ -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 `_ - - 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 `_ - - 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 `_ - - 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/ diff --git a/specs/skeleton.rst b/specs/skeleton.rst deleted file mode 100644 index b78320c..0000000 --- a/specs/skeleton.rst +++ /dev/null @@ -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 -========== - - diff --git a/specs/template.rst b/specs/template.rst deleted file mode 100644 index c5afd92..0000000 --- a/specs/template.rst +++ /dev/null @@ -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: - - -Other contributors: - - -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 diff --git a/tests/__init__.py b/tests/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/tests/test_titles.py b/tests/test_titles.py deleted file mode 100644 index 08f81bb..0000000 --- a/tests/test_titles.py +++ /dev/null @@ -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) diff --git a/tox.ini b/tox.ini deleted file mode 100644 index 61db5d9..0000000 --- a/tox.ini +++ /dev/null @@ -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