From 94801b9fc49210c5a4b545eb1a9e47039c0dd4e1 Mon Sep 17 00:00:00 2001
From: Kristal Dale <kristal.dale@intel.com>
Date: Wed, 26 Feb 2020 15:11:34 -0800
Subject: [PATCH] Update Documentation Contributor Guide

Update the Documentation Contributor Guide to use the existing
OpenStack doc contribution guides (for setup, making changes, making
a commit, making a review).

Change-Id: I6b0ffff61e71dd5a90d038841348d90e206c41ec
Signed-off-by: Kristal Dale <kristal.dale@intel.com>
---
 .../contributor/doc_contribute_guide.rst      | 81 ++++++++++---------
 .../code-submission-guide.rst                 |  4 +
 2 files changed, 48 insertions(+), 37 deletions(-)

diff --git a/doc/source/contributor/doc_contribute_guide.rst b/doc/source/contributor/doc_contribute_guide.rst
index d7c20b2ca..53d8819e8 100644
--- a/doc/source/contributor/doc_contribute_guide.rst
+++ b/doc/source/contributor/doc_contribute_guide.rst
@@ -9,55 +9,62 @@ documentation.
    :local:
    :depth: 1
 
-------------------
-General guidelines
-------------------
+----------
+Quickstart
+----------
 
 The StarlingX documentation uses reStructuredText (RST) markup syntax with
-Sphinx extensions. Most writing and markup conventions are based on the
-`OpenStack Documentation Contributor Guide <https://docs.openstack.org/doc-contrib-guide/index.html>`_.
+Sphinx extensions. It uses the same contribution setup and workflow as the OpenStack documentation.
 
-When writing documentation, follow the StarlingX documentation guidelines:
+* `OpenStack Documentation Contributor Guide <https://docs.openstack.org/doc-contrib-guide/index.html>`_.
 
-* `Writing style`_
-* `RST conventions`_
+**********************
+Setup for contribution
+**********************
 
-Verify that your changes render properly by `building the documentation locally <https://docs.openstack.org/doc-contrib-guide/docs-builds.html>`_.
+Follow the OpenStack instructions `Setting up for contribution <https://docs.openstack.org/doc-contrib-guide/quickstart/first-timers.html#setting-up-for-contribution>`_.
 
-******************
-Contribute content
-******************
+*************
+Make a change
+*************
 
-If you are looking for work to complete, review these reports:
+#. Make changes following the OpenStack instructions for
 
-* Refer to the `StarlingX documentation StoryBoard <https://storyboard.openstack.org/#!/project/starlingx/docs>`_ for topics that need content. Many topics have stub pages in the documentation with a link to the associated story.
+   #. `Starting a change <https://docs.openstack.org/infra/manual/developers.html#starting-a-change>`_
+   #. `Committing a change <https://docs.openstack.org/doc-contrib-guide/quickstart/first-timers.html#committing-a-change>`_.
+
+      .. note::
+
+         StarlingX requires the use of a **Signed-off-by** header. Use the
+         :command:`-s` option with :command:`git commit`.
+
+
+#. When writing documentation, follow `Writing style`_ and `RST conventions`_.
+
+#. Build the documentation locally to verify your changes before committing.
+   Follow the OpenStack instructions for
+   `Building documentation <https://docs.openstack.org/doc-contrib-guide/docs-builds.html>`_.
+
+#. If needed, follow up with edits to your patch following the OpenStack
+   instructions for `Responding to requests <https://docs.openstack.org/doc-contrib-guide/quickstart/first-timers.html#responding-to-requests>`_.
+
+
+--------------------------
+Find tasks and help needed
+--------------------------
+
+If you are looking for work to complete:
+
+* Refer to the
+  `StarlingX documentation StoryBoard <https://storyboard.openstack.org/#!/project/starlingx/docs>`_ for topics that need content. Many topics have stub pages in the documentation
+  with a link to the associated story.
 
 * Find open `documentation bugs on Launchpad <https://bugs.launchpad.net/starlingx/+bugs?field.tag=stx.docs>`_.
 
 
-When creating a Gerrit review, link the associated story, task, or bug in the
-comment, according to `Starlingx Code Submission Guidelines <https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines>`_.
-
-For example, link a story and task in a comment:
-
-::
-
-  Brief description of change.
-
-  Detailed description of change.
-
-  Story: $story_id
-  Task: $task_id
-
-Or, to link to the bug that the review fixes:
-
-::
-
-  Brief description of bug fix.
-
-  Detailed description of bug fix.
-
-  Closes-Bug: $bug_id
+If you make a contribution that has an the associated story, task, or bug in the
+comment, link to the related story or bug as described in the
+:ref:`Code Submission Guidelines <link-review-to-story>`.
 
 -----------------
 Docs organization
diff --git a/doc/source/developer_resources/code-submission-guide.rst b/doc/source/developer_resources/code-submission-guide.rst
index c03b2b884..e2c0af02c 100644
--- a/doc/source/developer_resources/code-submission-guide.rst
+++ b/doc/source/developer_resources/code-submission-guide.rst
@@ -1,3 +1,5 @@
+.. _code-submission-guide:
+
 ==========================
 Code Submission Guidelines
 ==========================
@@ -46,6 +48,8 @@ Code review process
 * For more details, refer the Openstack code review process, documented in the
   `Openstack Developer Guide <https://docs.openstack.org/infra/manual/developers.html#code-review>`_
 
+.. _link-review-to-story:
+
 ----------------------------
 Link reviews to story or bug
 ----------------------------