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:
parent
fcb640f696
commit
566194b034
|
@ -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
|
||||
|
|
|
@ -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.
|
|
@ -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
|
|
@ -0,0 +1,103 @@
|
|||
######################
|
||||
Introduction and Goals
|
||||
######################
|
||||
|
||||
What is the Contributor Guide?
|
||||
==============================
|
||||
First it’s important to note that we’re 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`.
|
|
@ -0,0 +1 @@
|
|||
.. include:: ../../../README.rst
|
|
@ -12,7 +12,7 @@ The OpenStack Contributor Guide
|
|||
|
||||
code-and-documentation
|
||||
users
|
||||
README file <readme>
|
||||
contributing/index
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
|
|
@ -1 +0,0 @@
|
|||
.. include:: ../../README.rst
|
Loading…
Reference in New Issue