First attempt of contributing to contrib-guide

This explains what our goals are, how to contribute, and what the
contributor portal is.

Also update our README with our storyboard project url for bug reports.

Change-Id: I3bd5dfb13e7fd9883283edb486aa2df957185170
This commit is contained in:
Mike Perez 2017-12-08 06:37:10 +11:00
parent fcb640f696
commit 566194b034
7 changed files with 151 additions and 3 deletions

View File

@ -15,4 +15,4 @@ format in the ``doc/build/`` directory.
* Free software: Apache license
* Documentation: http://docs.openstack.org/contributors
* Source: http://git.openstack.org/cgit/openstack/contributor-guide
* Bugs: TODO
* Bugs: https://storyboard.openstack.org/#!/project/913

View File

@ -0,0 +1,34 @@
######################
The Contributor Portal
######################
What is the Contributor Portal?
===============================
The `Contributor Portal <https://www.openstack.org/community/>`_ provides the
community with a landing page for new contributors to discover different ways
to contribute to OpenStack.
There are different contribution categories listed, such as Code &
Documentation and Users. Each one of these has their own contributor guide
listed on the main page of the :doc:`../index`.
Experienced contributors can find helpful reference links listed here too.
Proposing a New Contribution Category
=====================================
Send your proposal to the `OpenStack Developer List
<http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev>`_ with the
email subject prefixed with [contributor-portal]. This will start discussions
on accepting the new contribution category.
Proposing a Project Team Under Code & Documentation
===================================================
The project teams listed under the 'Code & Documentation' section come from
OpenStack's governance repository `project.yaml file
<http://git.openstack.org/cgit/openstack/governance/tree/reference/projects.yaml>`_.
This file is a list of projects that are recognized by the
`Technical Committee <https://governance.openstack.org/tc/>`_. Project teams
under this category should make sure their 'contributor' field is set to the
URL of their specific contributor guide. See the `project.yaml file
<http://git.openstack.org/cgit/openstack/governance/tree/reference/projects.yaml>`_
file for examples.

View File

@ -0,0 +1,11 @@
#####################################
Contributing to the Contributor Guide
#####################################
.. toctree::
:caption: Contributing to the Contributor Guide
:maxdepth: 2
intro
Bulding the guide <readme>
contributor-portal

View File

@ -0,0 +1,103 @@
######################
Introduction and Goals
######################
What is the Contributor Guide?
==============================
First its important to note that were not just talking about code projects.
OpenStack contributions come in different forms such as running meet ups,
identifying use cases (Product Working Group), documentation, testing, etc. Our
goal is to have these contributions valued equally.
The Contributor Guide aims to provide common documentation for all OpenStack
Contributors and help with on-boarding efforts.
Having the common documentation worked on by various projects will better help
prevent duplicated efforts, inconsistent documentation, and will also provide
more accurate information. Projects that have zero/outdated documentation can
also just use the Contributor Guide.
Where the Guide Is Used
=======================
At various OpenStack events, the Contributor Guide is used to help various
on-boarding programs:
* `The OpenStack Upstream Institute <https://docs.openstack.org/upstream-training/>`_
* `The Certified OpenStack Administrator Exam <https://www.openstack.org/coa>`_
* Project team on-boarding sessions
Project Specific Contributor Guides
===================================
Project teams should still have their own contributor documentation to cover
things listed under `Examples of Documentation that's NOT Common`_. A couple
examples of project team specific contributor guides are the `Nova team's
<https://docs.openstack.org/nova/latest/contributor/index.html>`_ and the
`Documentation team's <https://docs.openstack.org/doc-contrib-guide/>`_.
Adding/Updating Content
=======================
Before you modify or add new content first get familiar with OpenStack's
code/documentation practices. You can read the :doc:`../code-and-documentation`
for getting started.
Once you've read through the guide, use git to clone the Contributor Guide
repository::
git clone https://git.openstack.org/openstack/contributor-guide
Content Guidelines
==================
* No wall of text. The reader should feel like they can finish things on the
page in five minutes, instead of having yet another forgotten tab that
they'll never get back to.
* Use screen shots.
* Avoid covering every issue that can be hit along the way. Case by case basis
will be accepted depending on how common it is.
* No videos please. They're way too complicated to keep updated.
Common Content Only
-------------------
As the Contributor Guide is meant to be general so everyone can use it, here
are some helpful examples of what should be contributed. Examples of things
that are **not** common should be in your project team's specific documentation
which will be listed in the Contributor Portal.
Examples of Common Documentation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Setting up Git.
* Setting up IRC to communicate.
* Setting up Mailing Lists to communicate.
* Setting up appropriate accounts to contribute like Gerrit, Storyboard and
Launchpad.
* How to vote in elections.
Examples of Documentation that's NOT Common
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Some specific software tool only your project team uses.
* Specific procedures for doing things like bug triage.
Examples of Good Documentation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use chapters that have already been accepted to get a feel of what we're
looking for.
* :doc:`../irc`
* :doc:`../git`
* :doc:`../setup-gerrit`
How Can I Start Helping?
========================
Bug reports and tasks are all recorded in `Storyboard
<https://storyboard.openstack.org/#!/project/913>`_. If something isn't
assigned, it's available for you to take.
Get Help Contributing
=====================
We want you to succeed! You can ask for help on `IRC Freenode
<https://webchat.freenode.net/>`_ in channel #openstack-doc. You can also ask
for help on the `OpenStack Dev Mailing list
<http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev>`_ prefixing
your email subject with '[contributor-guide]'. If you're not familiar with
these ways of communicating, read the :doc:`../code-and-documentation`.

View File

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

View File

@ -12,7 +12,7 @@ The OpenStack Contributor Guide
code-and-documentation
users
README file <readme>
contributing/index
Indices and tables
==================

View File

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