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>

diff --git a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
index 6ec4ed8..71feb96 100644 (file)
--- a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
@@ -342,6 +342,7 @@ specified output folder directory.
 
 .. note:: Be sure to remove the `conf.py`, the static/ files and the output folder from the `<project>/docs/`. This is for testing only. Only commit the rst files and related content.
 
+.. _building-all-documentation:
 
 All Documentation
 -----------------

diff --git a/docs/guides/onap-developer/how-to-use-docs/index.rst b/docs/guides/onap-developer/how-to-use-docs/index.rst
index cd387df..941b153 100644 (file)
--- a/docs/guides/onap-developer/how-to-use-docs/index.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/index.rst
@@ -10,5 +10,6 @@ Creating Documentation
    documentation-guide
    style-guide
    include-documentation
-   converting-formats 
+   converting-formats
+   update-review
    addendum

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 (file)
index 0000000..033f2f0
--- /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`.