Added section about submodules

Added section about working with submodules as a
doc-team member. The instructions will be tested
once this commit is approved and merged (so I can
delete the tree and start from scratch).

Change-Id: I92edcf534b2b2ebc81167c2e032ed046f69d6716
Issue-Id: DOC-84
Signed-off-by: jsseidel <spence@research.att.com>

1 files changed, 101 insertions, 0 deletions

diff --git a/docs/guides/onap-developer/how-to-use-docs/update-review.rst b/docs/guides/onap-developer/how-to-use-docs/update-review.rst
new file mode 100644
index 000000000..033f2f085
--- /dev/null
+++ b/docs/guides/onap-developer/how-to-use-docs/update-review.rst
@@ -0,0 +1,101 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _updates-and-review:
+
+Updates and Review
+==================
+
+Most project owners will need only to concern themselves with their own
+project documentation. However, documentation team members and certain
+project owners will need to edit and test multiple documentation repositories.
+Fortunately, this is possible using git submodules.
+
+Git submodules
+--------------
+
+Git submodules are working copies of an upstream repository which you
+can clone inside your own project repositories. The documentation team
+uses them, for example, to keep up-to-date clones of each contributing
+project's :code:`docs` directory, found within the project repositories.
+
+For example:
+
+::
+
+   doc
+    +
+    |
+    + docs
+        +
+        |
+        + submodules
+               +
+               |
+               + ...
+               |
+               + cli.git
+               |    +
+               |    |
+               |    + ...
+               |    |
+               |    + docs
+               |    |
+               |    + ...
+               |
+               + appc.git
+               |    +
+               |    |
+               |    + ...
+               |    |
+               |    + docs
+               |    |
+               |    + ...
+               |
+               + ...
+
+
+When the doc team needs to build the master documentation, all the
+submodules are first updated before the build.
+
+Setting up Git Submodules as a Doc Team Member
+----------------------------------------------
+
+Look `here <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ for a
+complete discussion of how to work with git submodules in any git
+project. In this section, we'll focus on how to work with project submodules with
+respect to the documentation.
+
+Doc team members must frequently update submodules to contribute grammar
+and spelling fixes, for example. The following describes the
+best-practice for doing so.
+
+First, set up your environment according the :ref:`directions for building the entire documentation tree <building-all-documentation>`
+and make sure you can build the documentation locally.
+
+Next, we'll need to checkout a branch for each submodule.  Although you
+would rarely want to work on the master branch of a project repository
+when writing code, we'll stick to the master branch for documentation.
+That said, some project leaders might prefer you work with a specific
+branch. If so, you'll need to visit each submodule directory to checkout
+specific branches. Here, we'll check out the master branch of each submodule:
+
+.. code:: bash
+
+   git submodule foreach 'git checkout master'
+
+You might find that changes upstream have occurred since you cloned the
+submodules. To pull in the latest changes:
+
+.. code:: bash
+
+   git submodule foreach 'git pull'
+
+Requesting Reviews
+------------------
+
+The benefit of working with submodules in this way is that now you can
+make changes, do commits, and request reviews within the submodule
+directory just as if you had cloned the repository in its own directory.
+
+So, you commit as normal, with :code:`git commit -s`, and review as
+normal with :code:`git review`.