[ussuri][goal] Update contributor documentation

This patch updates/adds the contributor documentation to follow
the guidelines of the Ussuri cycle community goal[1].

[1] https://governance.openstack.org/tc/goals/selected/ussuri/project-ptl-and-contrib-docs.html

Story: #2007236
Task: #38524
Change-Id: I41b6fa23569047c8ed877902989a5ebd20c0c189

CONTRIBUTING.rst

@@ -1,16 +1,19 @@
-If you would like to contribute to the development of OpenStack,
+The source repository for this project can be found at:
-you must follow the steps in this page:
 
-   https://docs.openstack.org/infra/manual/developers.html
+   https://opendev.org/openstack/heat
 
-Once those steps have been completed, changes to OpenStack
+Pull requests submitted through GitHub are not monitored.
-should be submitted for review via the Gerrit tool, following
-the workflow documented at:
 
-   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 OpenStack Storyboard, not GitHub:
+Bugs should be filed on Storyboard,:
 
-   https://storyboard.openstack.org/#!/project/989
+   https://storyboard.openstack.org/#!/project/openstack/heat
+
+For more specific information about contributing to this repository, see the
+heat contributor guide:
+
+   https://docs.openstack.org/heat/latest/contributor/contributing.html

doc/source/_extra/.htaccess

@@ -1,5 +1,5 @@
-redirectmatch 301 ^/heat/([^/]+)/(architecture|pluginguide|schedulerhints|gmr|supportstatus)\.html$ /heat/$1/contributor/$2.html
+redirectmatch 301 ^/heat/([^/]+)/(architecture|pluginguide|schedulerhints|gmr|supportstatus)\.html$ /heat/$1/developing_guides/$2.html
-redirectmatch 301 ^/heat/([^/]+)/developing_guides/(index|architecture|pluginguide|schedulerhints|gmr|supportstatus)\.html$ /heat/$1/contributor/$2.html
 redirectmatch 301 ^/heat/([^/]+)/(scale_deployment)\.html$ /heat/$1/operating_guides/$2.html
 redirectmatch 301 ^/heat/([^/]+)/configuration/(api|clients)\.html /heat/$1/configuration/config-options.html
-redirectmatch 301 ^/heat/([^/]+)/contributing/(index|blueprints)\.html /heat/$1/contributor/$2.html
+redirectmatch 301 ^/heat/([^/]+)/contributing/(index|blueprints)\.html /heat/$1/developing_guides/$2.html
+redirectmatch 301 ^/heat/([^/]+)/contributor/(blueprints)\.html /heat/$1/developing_guides/$2.html

doc/source/contributor/blueprints.rst

@@ -1,84 +0,0 @@
-Blueprints and Specs
-====================
-
-The Heat team uses the `heat-specs
-<https://opendev.org/openstack/heat-specs>`_ repository for its
-specification reviews. Detailed information can be found `here
-<https://wiki.openstack.org/wiki/Blueprints#Heat>`_.
-
-Please note that we use a template for spec submissions. Please use the
-`template for the latest release
-<https://opendev.org/openstack/heat-specs/src/branch/master/specs/templates>`_.
-It is not required to fill out all sections in the template.
-
-You have to create a Story in StoryBoard `heat storyboard
-<https://storyboard.openstack.org/#!/project/989>`_. And create tasks that
-fit with the plan to implement this spec (A task to link to a patch in gerrit).
-
-Spec Notes
-----------
-
-
-There are occasions when a spec is approved and the code does not land in
-the cycle it was targeted for. For these cases, the workflow to get the spec
-into the next release is as below:
-
-* Anyone can propose a patch to heat-specs which moves a spec from the
-  previous release backlog into the new release directory.
-
-The specs which are moved in this way can be fast-tracked into the next
-release. Please note that it is required to re-propose the spec for the new
-release and it'll be evaluated based on the resources available and cycle
-priorities.
-
-Heat Spec Lite
---------------
-
-Lite specs are small feature requests tracked as StoryBoard stories, and tagged
-with 'spec-lite' and 'priority-wishlist' tag. These allow for submission
-and review of these feature requests before code is submitted.
-
-These can be used for small features that don’t warrant a detailed spec to be
-proposed, evaluated, and worked on. The team evaluates these requests as it
-evaluates specs.
-
-Once a `spec-lite` story has been approved/triaged as a
-Request for Enhancement(RFE), it’ll be targeted for a release.
-
-The workflow for the life of a spec-lite in StoryBoard is as follows:
-
-* File a story with a small summary of what the requested change is and
-  tag it as `spec-lite` and `priority-wishlist`.
-* Create tasks that fit to your plan in story.
-* The story is evaluated and marked with tag as `triaged` to announce
-  approval or `Invalid` to request a full spec or it's not a valided task.
-* The task is moved to `Progress` once the code is up and ready to
-  review.
-* The task is moved to `Merged` once the patch lands.
-* The story is moved to `Merged` once all tasks merged.
-
-The drivers team will discuss the following story reports in IRC meetings:
-
-* `heat stories <https://storyboard.openstack.org/#!/project_group/82>`_
-* `heat story filter <https://storyboard.openstack.org/#!/board/71>`_
-
-
-Lite spec Submission Guidelines
--------------------------------
-
-When a story is submitted, there is field that must be filled: ‘Description’.
-
-The ‘Description’ section must be a description of what you would like
-to see implemented in heat. The description should provide enough details for
-a knowledgeable developer to understand what is the existing problem and
-what’s the proposed solution.
-
-Add `spec-lite` tag to the story.
-
-
-Lite spec from existing stories
--------------------------------
-
-If there's an already existing story that describes a small feature suitable for
-a spec-lite, add a `spec-lite` tag to the story. There is no need to create a new
-story. The comments and history of the existing story are important for its review.

doc/source/contributor/contributing.rst

@@ -0,0 +1,47 @@
+============================
+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 heat.
+
+Communication
+~~~~~~~~~~~~~
+* IRC channel #heat at OFTC
+* Mailing list (prefix subjects with ``[heat]`` for faster responses)
+  http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
+
+Contacting the Core Team
+~~~~~~~~~~~~~~~~~~~~~~~~
+Please refer the `heat Core Team
+<https://review.opendev.org/admin/groups/b4b16f97f2b8416cb0111c0bec5df885bd779347,members>`_ contacts.
+
+New Feature Planning
+~~~~~~~~~~~~~~~~~~~~
+heat features are tracked on `Storyboard <https://storyboard.openstack.org/#!/project/openstack/heat>`_.
+
+Task Tracking
+~~~~~~~~~~~~~
+We track our tasks in `Storyboard <https://storyboard.openstack.org/#!/project/openstack/heat>`_.
+If you're looking for some smaller, easier work item to pick up and get started
+on, search for the 'low-hanging-fruit' tag.
+
+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/heat>`_.
+
+Getting Your Patch Merged
+~~~~~~~~~~~~~~~~~~~~~~~~~
+All changes proposed to the heat project require one or two +2 votes
+from heat core reviewers before one of the core reviewers can approve
+patch by giving ``Workflow +1`` vote.
+
+Project Team Lead Duties
+~~~~~~~~~~~~~~~~~~~~~~~~
+All common PTL duties are enumerated in the `PTL guide
+<https://docs.openstack.org/project-team-guide/ptl.html>`_.

doc/source/contributor/index.rst

@@ -1,24 +1,11 @@
 Heat Contributor Guidelines
 ===========================
 
-In the contributor guide, you will find documented policies for
-developing with heat. This includes the processes we use for
-blueprints and specs, bugs, contributor onboarding, core reviewer
-memberships, and other procedural items.
-
-.. note:: This guideline also includes documentation for developers.
-
 .. toctree::
    :maxdepth: 3
 
-   ../getting_started/on_devstack
+   contributing
-   blueprints
+
-   architecture
-   pluginguide
-   schedulerhints
-   gmr
-   supportstatus
-   rally_on_gates
 .. bugs
    contributor-onboarding
    core-reviewers

doc/source/developing_guides/blueprints.rst

@@ -0,0 +1,16 @@
+Blueprints and Specs
+====================
+
+You have to create a Story in StoryBoard `heat storyboard
+<https://storyboard.openstack.org/#!/project/989>`_. And create tasks that
+fit with the plan to implement this spec (A task to link to a patch in gerrit).
+
+.. note:: heat-spacs is no longer active, there's no requirement for any
+   feature to summit spac on it.
+
+Spec from existing stories
+-------------------------------
+
+If there's an already existing story that describes feature suitable to the
+story. There is no need to create a new story. The comments and history of
+the existing story are important for its review.

doc/source/developing_guides/index.rst

@@ -0,0 +1,26 @@
+Heat Deloper Guidelines
+=======================
+
+In the deloper guide, you will find documented policies for
+developing with heat. This includes the processes we use for
+stories (for bugs and features), contributor onboarding, core reviewer
+memberships, and other procedural items.
+
+.. note:: This guideline also includes documentation for developers.
+
+.. toctree::
+   :maxdepth: 3
+
+   ../getting_started/on_devstack
+   blueprints
+   architecture
+   pluginguide
+   schedulerhints
+   gmr
+   supportstatus
+   rally_on_gates
+.. bugs
+   contributor-onboarding
+   core-reviewers
+   gate-failure-triage
+   code-reviews

doc/source/index.rst

@@ -82,24 +82,31 @@ Using the Heat Service
 - `OpenStack Orchestration API v1 Reference`_
 - :python-heatclient-doc:`Python and CLI client <>`
 
-.. _`OpenStack Orchestration API v1 Reference`: https://docs.openstack.org/api-ref/orchestration/v1/
+.. _`OpenStack Orchestration API v1 Reference`: https://developer.openstack.org/api-ref/orchestration/v1/
 
 Developing Heat
 ===============
 
+.. toctree::
+    :maxdepth: 2
+
+    developing_guides/index
+
 .. toctree::
     :maxdepth: 1
 
-    contributor/index
-    getting_started/on_devstack
-    contributor/architecture
-    contributor/pluginguide
-    contributor/schedulerhints
-    contributor/gmr
-    contributor/supportstatus
-    contributor/rally_on_gates
     api/index
 
+For Contributors
+================
+
+* If you are a new contributor to Heat please refer: :doc:`contributor/contributing`
+
+  .. toctree::
+    :maxdepth: 2
+
+    contributor/index
+
 Indices and tables
 ==================
 

doc/source/operating_guides/scale_deployment.rst

@@ -48,7 +48,7 @@ Basic Architecture
 ------------------
 
 The heat architecture is as defined at :doc:`heat architecture
-<../contributor/architecture>` and shown in the diagram below, where we have
+<../developing_guides/architecture>` and shown in the diagram below, where we have
 a CLI that sends HTTP requests to the REST and CFN APIs, which in turn make
 calls using AMQP to the heat-engine::