bootstrap repository structure

Set up an initial structure for the repository which provides sections
for both specs and use cases, plus a guide on how to contribute.

Story: 2001628
Task: 6614
Task: 6615
Change-Id: If117f8b4d634707a9375a78292f916f47a4f8b0c
This commit is contained in:
Adam Spiers 2018-08-07 12:43:57 +01:00
parent 873e602528
commit 0a1d492996
16 changed files with 219 additions and 94 deletions

View File

@ -1,9 +1,18 @@
:orphan:
============================================= =============================================
Contributing to OpenStack's self-healing SIG Contributing to OpenStack's self-healing SIG
============================================= =============================================
If you would like to contribute to the development of OpenStack, you must If you would like to participate in discussions or contribute in any
follow the steps in this page: way to the design and development of self-healing in OpenStack, please
first see:
https://wiki.openstack.org/wiki/Self_healing_SIG
Contributions to the use-cases and specifications in this repository
are very welcome. To contribute to this repository, you must follow
the steps in this page:
http://docs.openstack.org/infra/manual/developers.html http://docs.openstack.org/infra/manual/developers.html

View File

@ -24,16 +24,24 @@ sys.path.insert(0, os.path.abspath('../..'))
extensions = [ extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
#'sphinx.ext.intersphinx', #'sphinx.ext.intersphinx',
'oslosphinx', 'openstackdocstheme',
'yasfb', 'yasfb',
] ]
html_theme = 'openstackdocs'
# openstackdocstheme options
repository_name = 'openstack/self-healing-sig'
bug_project = '917'
bug_tag = ''
# Feed configuration for yasfb # Feed configuration for yasfb
feed_base_url = 'http://specs.openstack.org/openstack/self-healing-sig' feed_base_url = 'http://specs.openstack.org/openstack/self-healing-sig'
feed_author = 'OpenStack Development Team' feed_author = 'OpenStack Self-healing SIG'
exclude_patterns = [ exclude_patterns = [
'template.rst', 'specs/template.rst',
'use-cases/template.rst',
] ]
# Optionally allow the use of sphinxcontrib.spelling to verify the # Optionally allow the use of sphinxcontrib.spelling to verify the
@ -55,7 +63,7 @@ source_suffix = '.rst'
master_doc = 'index' master_doc = 'index'
# General information about the project. # General information about the project.
project = u'self-healing-sig' project = u'Self-healing SIG'
copyright = u'%s, OpenStack Foundation' % datetime.date.today().year copyright = u'%s, OpenStack Foundation' % datetime.date.today().year
# If true, '()' will be appended to :func: etc. cross-reference text. # If true, '()' will be appended to :func: etc. cross-reference text.
@ -70,24 +78,5 @@ pygments_style = 'sphinx'
# -- Options for HTML output -------------------------------------------------- # -- Options for HTML output --------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
# html_theme_path = ["."]
# html_theme = '_theme'
# html_static_path = ['static']
# Output file base name for HTML help builder.
htmlhelp_basename = '%sdoc' % project
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass
# [howto/manual]).
latex_documents = [
('index',
'%s.tex' % project,
u'%s Documentation' % project,
u'OpenStack Foundation', 'manual'),
]
# Example configuration for intersphinx: refer to the Python standard library. # Example configuration for intersphinx: refer to the Python standard library.
#intersphinx_mapping = {'http://docs.python.org/': None} #intersphinx_mapping = {'http://docs.python.org/': None}

View File

@ -1,22 +0,0 @@
=============================================
Contributing to: self-healing-sig
=============================================
If you would like to contribute to the development of self-healing in
OpenStack, please first see:
https://wiki.openstack.org/wiki/Self_healing_SIG
To contribute to this repository, you must 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.

View File

@ -1,32 +1,25 @@
.. self-healing-sig documentation master file, created by ==========================
sphinx-quickstart on Tue Jul 9 22:26:36 2013. OpenStack Self-healing SIG
You can adapt this file completely to your liking, but it should at least ==========================
contain the root `toctree` directive.
self-healing-sig Design Specifications This documentation relates to some of the initiatives of OpenStack's
====================================== Self-healing SIG (Special Interest Group). For more information on
the SIG itself, see `the SIG's home page on the wiki
<https://wiki.openstack.org/wiki/Self-healing_SIG>`_.
.. toctree:: Contributions to this documentation are warmly encouraged; please see
:glob: :doc:`the guide to contributing <meta/CONTRIBUTING>`.
:maxdepth: 2
specs/*
self-healing-sig Repository Information
=======================================
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
README <readme> use-cases
contributing specs
Indices and tables Indices and tables
================== ==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search` * :ref:`search`

View File

@ -0,0 +1 @@
../../../CONTRIBUTING.rst

View File

@ -1,14 +0,0 @@
===============================
self-healing-sig
===============================
This documentation relates to the initiatives of OpenStack's
Self-healing SIG.
* Free software: Apache license
* Documentation: http://docs.openstack.org/developer/self-healing-sig
Features
--------
* TODO

1
doc/source/specs Symbolic link
View File

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

9
doc/source/specs.rst Normal file
View File

@ -0,0 +1,9 @@
Design specifications
=====================
When adding a new spec, please use ``specs/template.rst`` as a
starting point.
.. toctree::
:glob:
:maxdepth: 1

1
doc/source/use-cases Symbolic link
View File

@ -0,0 +1 @@
../../use-cases

11
doc/source/use-cases.rst Normal file
View File

@ -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/vitrage-mistral-integration.rst

View File

@ -1,4 +1,3 @@
pbr>=0.11,<2.0 pbr>=2.0.0
oslosphinx openstackdocstheme
sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
yasfb>=0.5.1 yasfb>=0.5.1

View File

@ -4,6 +4,10 @@ This work is licensed under a Creative Commons Attribution 3.0 Unported License.
http://creativecommons.org/licenses/by/3.0/legalcode http://creativecommons.org/licenses/by/3.0/legalcode
.. ..
This template is intended to encourage a certain level of consistency
between different use cases. However strict adherence to the structure
of this template is not required.
This template should be in ReSTructured text. The filename in the git This template should be in ReSTructured text. The filename in the git
repository should match the launchpad URL, for example a URL of repository should match the launchpad URL, for example a URL of
https://blueprints.launchpad.net/self-healing-sig/+spec/awesome-thing should be named https://blueprints.launchpad.net/self-healing-sig/+spec/awesome-thing should be named
@ -12,21 +16,19 @@ http://creativecommons.org/licenses/by/3.0/legalcode
For help with syntax, see http://sphinx-doc.org/rest.html For help with syntax, see http://sphinx-doc.org/rest.html
To test out your formatting, see http://www.tele3.cz/jbar/rest/rest.html To test out your formatting, see http://www.tele3.cz/jbar/rest/rest.html
============================= ===================================
The title of your blueprint The title of your self-healing spec
============================= ===================================
Include the URL of your launchpad blueprint:
https://blueprints.launchpad.net/self-healing-sig/+spec/example
Introduction paragraph -- why are we doing anything? Introduction paragraph -- why are we doing anything?
Problem description Problem description
=================== ===================
A detailed description of the problem. A detailed description of the problem.
Proposed change Proposed change
=============== ===============
@ -36,14 +38,15 @@ propose to solve this problem?
If this is one part of a larger effort make it clear where this piece ends. In 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? other words, what's the scope of this effort?
Include where in the self-healing-sig tree hierarchy this will reside. Include in which tree hierarchies of which projects this will reside.
Alternatives Alternatives
------------ ------------
This is an optional section, where it does apply we'd just like a demonstration 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. that some thought has been put into why the proposed approach is the best one.
Implementation Implementation
============== ==============
@ -66,7 +69,7 @@ Milestones
---------- ----------
Target Milestone for completion: Target Milestone for completion:
Juno-1 Stein-1
Work Items Work Items
---------- ----------
@ -79,7 +82,7 @@ but we're mostly trying to understand the timeline for implementation.
Dependencies Dependencies
============ ============
- Include specific references to specs and/or blueprints in self-healing-sig, or in other - Include specific references to specs and/or blueprints in this or other
projects, that this one either depends on or is related to. projects, that this one either depends on or is related to.
- Does this feature require any new library dependencies or code otherwise not - Does this feature require any new library dependencies or code otherwise not

View File

@ -15,7 +15,7 @@ deps = -r{toxinidir}/requirements.txt
commands = {posargs} commands = {posargs}
[testenv:docs] [testenv:docs]
commands = python setup.py build_sphinx commands = sphinx-build -W -b html doc/source doc/build/html
[testenv:spelling] [testenv:spelling]
deps = deps =

145
use-cases/template.rst Normal file
View File

@ -0,0 +1,145 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported License.
http://creativecommons.org/licenses/by/3.0/legalcode
..
This template is intended to encourage a certain level of consistency
between different use cases. However strict adherence to the structure
of this template is not required.
This template should be in ReSTructured text. The filename in the git
repository should match the launchpad URL, for example a URL of
https://blueprints.launchpad.net/self-healing-sig/+spec/awesome-thing should be named
awesome-thing.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, see http://www.tele3.cz/jbar/rest/rest.html
=======================================
The title of your self-healing 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 ________ has a _______
failure, I want to be notified of all affected _______. Moreover, I
want _______ in order that ________ will continue to function.
Problem description
===================
..
A more detailed description of the fault management 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.
Fault class
===========
..
Please choose which of these classes are relevant and delete the
others. If you can think of a new class which should be listed
here, please update the template.
Hardware failure
Software error
Performance degradation
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.
* Zabbix
* Vitrage
* Mistral
Remediation class
=================
..
Please choose which of these classes are relevant and delete the
others. If you can think of a new class which should be listed
here, please update the template.
Proactive / preemptive
Predictive
Reactive
Fault detection
===============
..
Describe the exact nature of the fault, which components
will be needed to automatically detect it, and how they
should be configured or used for the detection.
This may include details about relevant log streams, alarms,
error codes etc.
Inputs and decision-making
==========================
..
Describe how decisions about the remediation action are taken. In
particular list any other components or inputs which may provide
additional context to help determine appropriate remediation of the
fault.
Remediation
===========
..
Describe how the fault may be remediated. 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
self-healing-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?

View File

Before

Width:  |  Height:  |  Size: 74 KiB

After

Width:  |  Height:  |  Size: 74 KiB