Added documentation for eslint-config-openstack

Added documentation to include release guidelines.
Change-Id: I2c2cd929283868dac415f986f541d0ec5741ef17
This commit is contained in:
Elizabeth Elwell 2016-08-17 14:23:51 +01:00
parent 4549ae61e2
commit c457a0e9d8
6 changed files with 214 additions and 0 deletions

75
doc/source/conf.py Executable file
View File

@ -0,0 +1,75 @@
# -*- 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 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',
'oslosphinx'
]
# 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'eslint-config-openstack'
copyright = u'2016, OpenStack Foundation'
# 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 --------------------------------------------------
# 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.
#intersphinx_mapping = {'http://docs.python.org/': None}

View File

@ -0,0 +1,73 @@
.. _contributing:
=======================================
Contributing to eslint-config-openstack
=======================================
If you're interested in contributing to the eslint-config-openstack
project, the following will help get you started.
Contributor License Agreement
-----------------------------
.. index::
single: license; agreement
In order to contribute to the project, you need to have
signed OpenStack's contributor's agreement.
.. seealso::
* http://docs.openstack.org/infra/manual/developers.html
* http://wiki.openstack.org/CLA
LaunchPad Project
-----------------
Most of the tools used for OpenStack depend on a launchpad.net ID for
authentication.
.. seealso::
* https://launchpad.net
* https://launchpad.net/eslint-config-openstack
Project Hosting Details
-------------------------
Mailing list (prefix subjects with ``[eslint-config-openstack]`` for faster responses)
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Code Hosting
https://github.com/openstack/eslint-config-openstack
Code Review
https://review.openstack.org/#/q/status:open+project:openstack/eslint-config-openstack,n,z
Rules only land with consensus
------------------------------
Patches that activate, deactivate, or modify rules, should only be merged if a consensus of
reviewers is reached. In this case, consensus means at least five positive votes (+1 or +2),
with no -1 votes. Cores may not override and/or ignore -1 votes.
Library upgrades require two cores
----------------------------------
Patches that upgrade eslint only require two core approvers to land. These patches must add new
upstream rules in a deactivated state, and delete any deprecated rules.
Policy upgrades require all cores
---------------------------------
Updates to policies and governance on this project require +2 votes from all direct cores on the
project. Core votes from the parent OpenStack QA project are optional.
Patches should be abandoned after a month of inactivity
-------------------------------------------------------
Cores should attempt to keep the list of extant patches small and managable. As such, they should
talk to any author whose patch has failed to garner the necessary support, and has experienced
one month of inactivity. Reasonable notice should be given to the author before a patch is
abandoned.

25
doc/source/index.rst Normal file
View File

@ -0,0 +1,25 @@
===========================================================
Welcome to eslint-config-openstack developer documentation!
===========================================================
Introduction
============
OpenStack has a set of style guidelines for clarity. OpenStack is a very large
code base, spanning dozens of git trees, with over a thousand developers contributing
every 6 months. As such, common style helps developers understand code in reviews,
move between projects smoothly, and overall make the code more maintainable.
Even though eslint permits overriding rules on a per-project basis, it should be
the goal of every project to stay as close to the common guidelines as possible.
Administrator's Guide
=====================
.. toctree::
:maxdepth: 1
Introduction to eslint-config-openstack <readme>
Installing eslint-config-openstack in your project <installation>
Contributing to eslint-config-openstack <contributing>
Releasing a version of eslint-config-openstack <releasing>

View File

@ -0,0 +1,14 @@
.. _installation:
==================================================
Installing eslint-config-openstack in your project
==================================================
To add these rules to your project, follow these steps.
1. Install the npm package to your project:
`npm install --save-dev eslint eslint-config-openstack`
2. Add `extends: "openstack"` to your `.eslintrc` yaml file.
If your project is using ES2015, add `extends: "openstack/es2015"` instead.

1
doc/source/readme.rst Normal file
View File

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

26
doc/source/releasing.rst Normal file
View File

@ -0,0 +1,26 @@
======================================
How to release eslint-config-openstack
======================================
Only follow these steps if you have authority to release a version of eslint-config-openstack.
1. Ensure that you have gpg set up locally.
If you do not currently have gog installed:
`brew install gpg gpg2`
Set up your gpg key:
https://wiki.openstack.org/wiki/Oslo/ReleaseProcess#Setting_Up_GPG
2. `git pull --ff-only`
3. `git tag -s <version number>`
4. `git push gerrit <version number>`
Git wont have a remote named gerrit until the first time git-review runs.
You may need to run git review -s before the push.
For more information see:
http://docs.openstack.org/infra/manual/drivers.html#tagging-a-release