diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fd16e16 --- /dev/null +++ b/.gitignore @@ -0,0 +1,36 @@ +*.py[cod] + +# Packages +*.egg +*.egg-info +dist +build +eggs +parts +sdist +develop-eggs +.installed.cfg + +# Installer logs +pip-log.txt + +# Unit test / coverage reports +.tox +nosetests.xml +.testrepository + +# Mr Developer +.mr.developer.cfg +.project +.pydevproject + +# Sphinx +doc/build + +# pbr generates these +AUTHORS +ChangeLog + +# Editors +*~ +.*.swp diff --git a/.zuul.yaml b/.zuul.yaml new file mode 100644 index 0000000..a43149c --- /dev/null +++ b/.zuul.yaml @@ -0,0 +1,3 @@ +- project: + templates: + - publish-openstack-sphinx-docs diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000..12fb6a6 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,98 @@ +:orphan: + +============================================= +Contributing to OpenStack's auto-scaling SIG +============================================= + +If you would like to participate in discussions or contribute in any +way to the design and development of auto-scaling in OpenStack, please +first see the following wiki to understand the SIG's mission, scope, +and other supporting information: + + https://wiki.openstack.org/wiki/Auto-scaling_SIG + +Many forms of contribution are valuable to the community, including but not +limited to the following: + +- `Documentation of use cases <#use-cases>`_, including implementation details if available +- `Design specs`_ +- `Code`_ +- `Discussions`_ on all the above and other topics + +Everyone is warmly encouraged to get involved in whatever capacity you +see fit. + +Discussions +----------- + +Discussions take place: + +- on `the openstack-discuss mailing list + `_ + with ``[auto-scaling-sig]`` in the Subject header, +- `the SIG's storyboard + `_, +- and in patch reviews. + +Links to all resources can also be found in the `SIG wiki section on +community`_. + +.. _`SIG wiki section on community`: https://wiki.openstack.org/wiki/auto-scaling_SIG#Community_Infrastructure_.2F_Resources + +Use cases +--------- + +The SIG serves to facilitate the discussion and documentation of auto-scaling +use cases at all stages of development from a seed idea to a fully tested use +case. + +To call attention to a use case, please start the discussion in `one +of the established communication channels <#discussions>`_. + +Alternatively, directly submit a patch to document the use case, +following the format laid out in the `template file +`__ +in `the use-cases/ directory +`_ +of `the auto-scaling-sig repository +`_. + +See `Submitting a change`_ for more information. + +Design specs +------------ + +Design specs are proposed implementations of auto-scaling +functionality across projects. To author a new design spec, please +follow the format laid out in the `template file +`__ +in `the specs/ directory +`_ +of `the auto-scaling-sig repository`_. + +See `Submitting a change`_ for more information. + +Code +---- + +`The auto-scaling-sig repository`_ also holds any relevant +cross-project code, tests, and documentation that do not naturally +belong in a single project repository. + +See `Submitting a change`_ for more information. + +Submitting a change +------------------- + +To submit a change to this repository, please follow the steps in this page: + + http://docs.openstack.org/infra/manual/developers.html + +If you already have a good understanding of how the system works and your +OpenStack accounts are set up, you can skip to the development workflow +section of this documentation to learn how changes to OpenStack should be +submitted for review via the Gerrit tool: + + http://docs.openstack.org/infra/manual/developers.html#development-workflow + +Pull requests submitted through GitHub will be ignored. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..75a29c4 --- /dev/null +++ b/LICENSE @@ -0,0 +1,3 @@ +This work is licensed under a Creative Commons Attribution 3.0 Unported License. + +http://creativecommons.org/licenses/by/3.0/legalcode diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..c978a52 --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,6 @@ +include AUTHORS +include ChangeLog +exclude .gitignore +exclude .gitreview + +global-exclude *.pyc diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..4e3785a --- /dev/null +++ b/README.rst @@ -0,0 +1,25 @@ +========================== +OpenStack auto-scaling SIG +========================== + +This repository is for storing documentation and code which relates to +the initiatives of OpenStack's auto-scaling SIG. + +For a comprehensive set of information and resources regarding the +SIG, please see `the SIG's wiki page +`_. + +The documentation in this repository is automatically published +online in HTML format: + +- http://docs.openstack.org/auto-scaling-sig/latest/ + +License +------- + +Except for where stated otherwise: + +* Any specs, use-cases, and other documentation are released under + a `Creative Commons Attribution license `_. +* Any code is released under `the Apache License 2.0 + `_. diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100755 index 0000000..b5a61e8 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,82 @@ +# -*- coding: utf-8 -*- +# 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 datetime +import os +import sys + +sys.path.insert(0, os.path.abspath('../..')) +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + #'sphinx.ext.intersphinx', + 'openstackdocstheme', + 'yasfb', +] + +html_theme = 'openstackdocs' + +# openstackdocstheme options +repository_name = 'openstack/auto-scaling-sig' +bug_project = '917' +bug_tag = '' + +# Feed configuration for yasfb +feed_base_url = 'http://specs.openstack.org/openstack/auto-scaling-sig' +feed_author = 'OpenStack Auto-scaling SIG' + +exclude_patterns = [ + 'specs/template.rst', + 'use-cases/template.rst', +] + +# Optionally allow the use of sphinxcontrib.spelling to verify the +# spelling of the documents. +try: + import sphinxcontrib.spelling + extensions.append('sphinxcontrib.spelling') +except ImportError: + pass + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'auto-scaling SIG' +copyright = u'%s, OpenStack Foundation' % datetime.date.today().year + +# 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 = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for HTML output -------------------------------------------------- + +# Example configuration for intersphinx: refer to the Python standard library. +#intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..9debf01 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,25 @@ +========================== +OpenStack Auto-scaling SIG +========================== + +This documentation relates to some of the initiatives of OpenStack's +Auto-scaling SIG (Special Interest Group). For more information on +the SIG itself, see `the SIG's home page on the wiki +`_. + +Contributions to this documentation are warmly encouraged; please see +:doc:`the guide to contributing `. + + +.. toctree:: + :maxdepth: 2 + + use-cases + specs + + +Indices and tables +================== + +* :ref:`search` + diff --git a/doc/source/meta/CONTRIBUTING.rst b/doc/source/meta/CONTRIBUTING.rst new file mode 120000 index 0000000..ac9338f --- /dev/null +++ b/doc/source/meta/CONTRIBUTING.rst @@ -0,0 +1 @@ +../../../CONTRIBUTING.rst \ No newline at end of file diff --git a/doc/source/specs b/doc/source/specs new file mode 120000 index 0000000..87a4030 --- /dev/null +++ b/doc/source/specs @@ -0,0 +1 @@ +../../specs \ No newline at end of file diff --git a/doc/source/specs.rst b/doc/source/specs.rst new file mode 100644 index 0000000..7391498 --- /dev/null +++ b/doc/source/specs.rst @@ -0,0 +1,11 @@ +Design specifications +===================== + +When adding a new spec, please use ``specs/template.rst`` as a +starting point. + +.. toctree:: + :glob: + :maxdepth: 1 + + specs/* diff --git a/doc/source/use-cases b/doc/source/use-cases new file mode 120000 index 0000000..9f85718 --- /dev/null +++ b/doc/source/use-cases @@ -0,0 +1 @@ +../../use-cases \ No newline at end of file diff --git a/doc/source/use-cases.rst b/doc/source/use-cases.rst new file mode 100644 index 0000000..d9a62b0 --- /dev/null +++ b/doc/source/use-cases.rst @@ -0,0 +1,11 @@ +Use cases +========= + +When adding a new use case, please use ``use-cases/template.rst`` as +a starting point. + +.. toctree:: + :glob: + :maxdepth: 1 + + use-cases/* diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..3d69233 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +pbr>=2.0.0 +openstackdocstheme +yasfb>=0.5.1 diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..3aeda6b --- /dev/null +++ b/setup.cfg @@ -0,0 +1,24 @@ +[metadata] +name = auto-scaling-sig +summary = This repository is for storing documentation and code which relates to the initiatives of OpenStack's auto-scaling SIG +description-file = + README.rst +author = OpenStack +author-email = openstack-discuss@lists.openstack.org +home-page = https://docs.openstack.org/auto-scaling-sig/latest/ +classifier = + Environment :: OpenStack + Intended Audience :: Developers + License :: OSI Approved :: Apache Software License + Operating System :: POSIX :: Linux + +[build_sphinx] +source-dir = doc/source +build-dir = doc/build +all_files = 1 + +[pbr] +warnerrors = True + +[upload_sphinx] +upload-dir = doc/build/html diff --git a/setup.py b/setup.py new file mode 100755 index 0000000..70c2b3f --- /dev/null +++ b/setup.py @@ -0,0 +1,22 @@ +#!/usr/bin/env python +# 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 + +setuptools.setup( + setup_requires=['pbr'], + pbr=True) diff --git a/specs/.gitignore b/specs/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/specs/template.rst b/specs/template.rst new file mode 100644 index 0000000..137848f --- /dev/null +++ b/specs/template.rst @@ -0,0 +1,80 @@ +.. + This template is intended to encourage a certain level of + consistency between different use cases. Adherence to the structure + of this template is recommended but not strictly required. + + This template should be in ReSTructured text. For help with syntax, + see . To test out your formatting, + see . + +=================================== +The title of your auto-scaling spec +=================================== + +Introduction paragraph -- why are we doing anything? + + +Problem description +=================== + +A detailed description of the problem. + + +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? + +Include in which tree hierarchies of which projects this will reside. + +Alternatives +------------ + +This is an optional section; where it does apply we'd just like a demonstration +that some thought has been put into why the proposed approach is the best 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: + + +Can optionally can list additional ids if they intend on doing +substantial implementation work on this blueprint. + +Milestones +---------- + +Target Milestone for completion: + Train-1 + +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 this or other + projects, that this one either depends on or is related to. + +- 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? diff --git a/test-requirements.txt b/test-requirements.txt new file mode 100644 index 0000000..e69de29 diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..005e371 --- /dev/null +++ b/tox.ini @@ -0,0 +1,28 @@ +[tox] +minversion = 1.6 +envlist = docs +skipsdist = True + +[testenv] +usedevelop = True +install_command = pip install -U {opts} {packages} +setenv = + VIRTUAL_ENV={envdir} +deps = -r{toxinidir}/requirements.txt + -r{toxinidir}/test-requirements.txt + +[testenv:venv] +basepython = python3 +commands = {posargs} + +[testenv:docs] +basepython = python3 +commands = sphinx-build -W -b html doc/source doc/build/html + +[testenv:spelling] +basepython = python3 +deps = + -r{toxinidir}/requirements.txt + sphinxcontrib-spelling + PyEnchant +commands = sphinx-build -b spelling doc/source doc/build/spelling diff --git a/use-cases/template.rst b/use-cases/template.rst new file mode 100644 index 0000000..797faf0 --- /dev/null +++ b/use-cases/template.rst @@ -0,0 +1,95 @@ +.. + This template is intended to encourage a certain level of + consistency between different use cases. Adherence to the structure + of this template is recommended but not strictly required. + + This template should be in ReSTructured text. For help with syntax, + see . To test out your formatting, + see . + +======================================= +The title of your auto-scaling use case +======================================= + +.. + Please fill in the blanks in this use case statement, or rephrase + as appropriate. + +As a cloud operator, whenever one of my cloud's ____________________, +I want ____________________________. + + +Problem description +=================== + +.. + A more detailed description of the auto-scaling scenario; + however it is not advised to duplicate details covered in the + sections below. If the problem is not too complex, it may be more + appropriate to simply delete this section and provide the details in + the sections below. + + +OpenStack projects used +======================= + +.. + Please provide a list of projects (OpenStack and otherwise) which + may be used in order to implement this use case. If no + implementation exists yet, suggestions are sufficient here. + +* ... +* ... + + +Inputs and decision-making +========================== + +.. + Describe how decisions about when/how to auto-scale are taken. In + particular list any other components or inputs which may provide + additional context to help determine the correct action. + + +Auto-scaling +============ + +.. + Describe how the auto-scaling may occur. If there may be different + approaches available, please list them all. + + +Existing implementation(s) +========================== + +.. + If there are one or more existing implementations of this use case, + please give as many details as possible, in order that operators can + re-implement the use case in their own clouds. However any + information is better than no information! Linking to external + documents is perfectly acceptable. + + +Future work +=========== + +.. + Please link from here to any relevant specs. If a cross-project + spec is required, it can be placed under ../specs/ in this + repository. + + Please also make sure that any linked specs contain back-links + to this use case for maximum discoverability. + + +Dependencies +============ + +.. + - Include specific references to specs and/or blueprints in + auto-scaling-sig, or in other projects, that this one either depends + on or is related to. + + - 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?