From d124ab2090fbe3564a3cea213891d8032c0fea1c Mon Sep 17 00:00:00 2001
From: Mark Goddard <mark@stackhpc.com>
Date: Thu, 21 May 2020 11:17:12 +0100
Subject: [PATCH] [Community goal] Update the contributor guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Adapted from Kolla Ansible guide
(https://review.opendev.org/#/c/729642).
Co-Authored-By: Michal Nasiadka <mnasiadka@gmail.com>
Co-Authored-By: Radosław Piliszek <radoslaw.piliszek@gmail.com>
Change-Id: I3a5a1d0a6fb65b95166fe564e15b655d72002639
Story: #2007236
Task: #39821
---
CONTRIBUTING.rst | 24 ++---
doc/source/contributor/contributing.rst | 108 +++++++++++++++++++++++
doc/source/contributor/index.rst | 16 ++++
doc/source/contributor/release-notes.rst | 45 ++++++++++
doc/source/development/contributing.rst | 3 +-
doc/source/index.rst | 8 ++
6 files changed, 192 insertions(+), 12 deletions(-)
create mode 100644 doc/source/contributor/contributing.rst
create mode 100644 doc/source/contributor/index.rst
create mode 100644 doc/source/contributor/release-notes.rst
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 8ab5bd93..414de1ba 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1,17 +1,19 @@
-If you would like to contribute to the development of OpenStack, you must
-follow the steps in this page:
+The source repository for this project can be found at:
- https://docs.openstack.org/infra/manual/developers.html
+ https://opendev.org/openstack/kayobe
-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:
+Pull requests submitted through GitHub are **not** monitored.
- https://docs.openstack.org/infra/manual/developers.html#development-workflow
+To start contributing to OpenStack, follow the steps in the contribution guide
+to set up and use Gerrit:
-Pull requests submitted through GitHub will be ignored.
+ https://docs.openstack.org/contributors/code-and-documentation/quick-start.html
-Bugs should be filed on StoryBoard, not GitHub:
+Bugs should be filed on Storyboard:
- https://storyboard.openstack.org/
+ https://storyboard.openstack.org/#!/project/openstack/kayobe
+
+For more specific information about contributing to this repository, see the
+Kayobe contributor guide:
+
+ https://docs.openstack.org/kayobe/latest/contributor/contributing.html
diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst
new file mode 100644
index 00000000..ce07c6b5
--- /dev/null
+++ b/doc/source/contributor/contributing.rst
@@ -0,0 +1,108 @@
+============================
+So You Want to Contribute...
+============================
+
+For general information on contributing to OpenStack, please check out the
+`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
+It covers all the basics that are common to all OpenStack projects: the
+accounts you need, the basics of interacting with our Gerrit review system,
+how we communicate as a community, etc.
+
+Below will cover the more project specific information you need to get started
+with Kayobe.
+
+Basics
+~~~~~~
+
+The source repository for this project can be found at:
+
+ https://opendev.org/openstack/kayobe
+
+Communication
+~~~~~~~~~~~~~
+
+Kayobe shares communication channels with Kolla.
+
+IRC Channel
+ ``#openstack-kolla`` (`channel logs`_) on Freenode
+
+Weekly Meetings
+ On Wednesdays at 15:00 UTC in the IRC channel (`meetings logs`_)
+
+Mailing list (prefix subjects with ``[kolla]``)
+ http://lists.openstack.org/pipermail/openstack-discuss/
+
+Meeting Agenda
+ https://wiki.openstack.org/wiki/Meetings/Kolla
+
+Whiteboard (etherpad)
+ Keeping track of CI gate status, release status, stable backports,
+ planning and feature development status.
+ https://etherpad.openstack.org/p/KollaWhiteBoard
+
+.. _channel logs: http://eavesdrop.openstack.org/irclogs/%23openstack-kolla/
+.. _meetings logs: http://eavesdrop.openstack.org/meetings/kolla/
+
+Contacting the Core Team
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The list in alphabetical order (on first name):
+
++-----------------------+---------------+------------------------------------+
+| Name | IRC nick | Email address |
++=======================+===============+====================================+
+| Doug Szumski | dougsz | doug@stackhpc.com |
++-----------------------+---------------+------------------------------------+
+| John Garbutt | johnthetubaguy| john@johngarbutt.com |
++-----------------------+---------------+------------------------------------+
+| Kevin Tibi | ktibi | kevintibi@hotmail.com |
++-----------------------+---------------+------------------------------------+
+| Mark Goddard | mgoddard | mark@stackhpc.com |
++-----------------------+---------------+------------------------------------+
+| Pierre Riteau | priteau | pierre@stackhpc.com |
++-----------------------+---------------+------------------------------------+
+| Will Szumski | jovial | will@stackhpc.com |
++-----------------------+---------------+------------------------------------+
+
+The current effective list is also available from Gerrit:
+https://review.opendev.org/#/admin/groups/1875,members
+
+New Feature Planning
+~~~~~~~~~~~~~~~~~~~~
+
+New features are discussed via IRC or mailing list (with [kolla] prefix).
+Kayobe project keeps RFEs in `Storyboard
+<https://storyboard.openstack.org/#!/project/openstack/kayobe>`__. Specs are
+welcome but not strictly required.
+
+Task Tracking
+~~~~~~~~~~~~~
+
+Kolla project tracks tasks in `Storyboard
+<https://storyboard.openstack.org/#!/project/openstack/kayobe>`__. Note this
+is the same place as for bugs.
+
+A more lightweight task tracking is done via etherpad - `Whiteboard
+<https://etherpad.openstack.org/p/KollaWhiteBoard>`__.
+
+Reporting a Bug
+~~~~~~~~~~~~~~~
+
+You found an issue and want to make sure we are aware of it? You can do so
+on `Storyboard <https://storyboard.openstack.org/#!/project/openstack/kayobe>`__.
+Note this is the same place as for tasks.
+
+Getting Your Patch Merged
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most changes proposed to Kayobe require two +2 votes from core reviewers
+before +W. A release note is required on most changes as well. Release notes
+policy is described in :ref:`its own section <release-notes>`.
+
+Significant changes should have documentation and testing provided with them.
+
+Project Team Lead Duties
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+All common PTL duties are enumerated in the `PTL guide <https://docs.openstack.org/project-team-guide/ptl.html>`_.
+Release tasks are described in the :doc:`Kayobe releases guide <../development/releases>`.
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
new file mode 100644
index 00000000..adfce774
--- /dev/null
+++ b/doc/source/contributor/index.rst
@@ -0,0 +1,16 @@
+=================
+Contributor Guide
+=================
+
+This guide is for contributors of the Kayobe project. It includes
+information on proposing your first patch and how to participate in the
+community. It also covers responsibilities of core reviewers and the Project
+Team Lead (PTL), and information about development processes.
+
+We welcome everyone to join our project!
+
+.. toctree::
+ :maxdepth: 1
+
+ contributing
+ release-notes
diff --git a/doc/source/contributor/release-notes.rst b/doc/source/contributor/release-notes.rst
new file mode 100644
index 00000000..673779b9
--- /dev/null
+++ b/doc/source/contributor/release-notes.rst
@@ -0,0 +1,45 @@
+.. _release-notes:
+
+=============
+Release notes
+=============
+
+Kayobe (just like Kolla) uses the following release notes sections:
+
+- ``features`` --- for new features or functionality; these should ideally
+ refer to the blueprint being implemented;
+- ``fixes`` --- for fixes closing bugs; these must refer to the bug being
+ closed;
+- ``upgrade`` --- for notes relevant when upgrading from previous version;
+ these should ideally be added only between major versions; required when
+ the proposed change affects behaviour in a non-backwards compatible way or
+ generally changes something impactful;
+- ``deprecations`` --- to track deprecated features; relevant changes may
+ consist of only the commit message and the release note;
+- ``prelude`` --- filled in by the PTL before each release or RC.
+
+Other release note types may be applied per common sense.
+Each change should include a release note unless being a ``TrivialFix``
+change or affecting only docs or CI. Such changes should `not` include
+a release note to avoid confusion.
+Remember release notes are mostly for end users which, in case of Kolla,
+are OpenStack administrators/operators.
+In case of doubt, the core team will let you know what is required.
+
+To add a release note, run the following command:
+
+.. code-block:: console
+
+ tox -e venv -- reno new <summary-line-with-dashes>
+
+All release notes can be inspected by browsing ``releasenotes/notes``
+directory.
+
+To generate release notes in HTML format in ``releasenotes/build``, run:
+
+.. code-block:: console
+
+ tox -e releasenotes
+
+Note this requires the release note to be tracked by ``git`` so you
+have to at least add it to the ``git``'s staging area.
diff --git a/doc/source/development/contributing.rst b/doc/source/development/contributing.rst
index 7086829a..3ab60407 100644
--- a/doc/source/development/contributing.rst
+++ b/doc/source/development/contributing.rst
@@ -1,4 +1,5 @@
=================
How to Contribute
=================
-.. include:: ../../../CONTRIBUTING.rst
+
+The contributor guide has moved to :doc:`../contributor/contributing`.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index c10eff56..ed6977f1 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -50,6 +50,14 @@ Advanced Documentation
control-plane-service-placement
custom-ansible-playbooks
+Contributor Guide
+-----------------
+
+.. toctree::
+ :maxdepth: 2
+
+ contributor/index
+
Developer Documentation
-----------------------
--
GitLab