summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorjsseidel <spence@research.att.com>2017-09-19 13:29:23 -0400
committerjsseidel <spence@research.att.com>2017-09-19 13:33:04 -0400
commit8066619a4440e723a256cecfc93ee577b6f156e6 (patch)
tree8b8587721b6da30df7d6c74c786599b4e40a3732 /docs
parentc028ba557d33cddd5c7a8c346cc2a88afb853279 (diff)
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>
Diffstat (limited to 'docs')
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/include-documentation.rst1
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/index.rst3
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/update-review.rst101
3 files changed, 104 insertions, 1 deletions
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 6ec4ed849..71feb9607 100644
--- 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 cd387df51..941b15347 100644
--- 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
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`.