docs/guides/onap-developer/how-to-use-docs/update-review.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _updates-and-review:
   4
   5 Updates and Review
   6 ==================
   7
   8 **NOTE: THIS SECTION IS UNDER HEAVY DEVELOPMENT USE WITH CAUTION**
   9
  10 Most project owners will need only to concern themselves with their own
  11 project documentation. However, documentation team members and certain
  12 project owners will need to edit and test multiple documentation repositories.
  13 Fortunately, this is possible using git submodules.
  14
  15 Git submodules
  16 --------------
  17
  18 Git submodules are working copies of an upstream repository which you
  19 can clone inside your own project repositories. The documentation team
  20 uses them, for example, to keep up-to-date clones of each contributing
  21 project's :code:`docs` directory, found within the project repositories.
  22
  23 For example:
  24
  25 ::
  26
  27    doc
  28     +
  29     |
  30     + docs
  31         +
  32         |
  33         + submodules
  34                +
  35                |
  36                + ...
  37                |
  38                + cli.git
  39                |    +
  40                |    |
  41                |    + ...
  42                |    |
  43                |    + docs
  44                |    |
  45                |    + ...
  46                |
  47                + appc.git
  48                |    +
  49                |    |
  50                |    + ...
  51                |    |
  52                |    + docs
  53                |    |
  54                |    + ...
  55                |
  56                + ...
  57
  58
  59 When the doc team needs to build the master documentation, all the
  60 submodules are first updated before the build.
  61
  62 Setting up Git Submodules as a Doc Team Member
  63 ----------------------------------------------
  64
  65 Look `here <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ for a
  66 complete discussion of how to work with git submodules in any git
  67 project. In this section, we'll focus on how to work with project submodules with
  68 respect to the documentation.
  69
  70 Doc team members must frequently update submodules to contribute grammar
  71 and spelling fixes, for example. The following describes the
  72 best-practice for doing so.
  73
  74 First, set up your environment according the :ref:`directions for building the entire documentation tree <building-all-documentation>`
  75 and make sure you can build the documentation locally.
  76
  77 Next, we'll need to checkout a branch for each submodule.  Although you
  78 would rarely want to work on the master branch of a project repository
  79 when writing code, we'll stick to the master branch for documentation.
  80 That said, some project leaders might prefer you work with a specific
  81 branch. If so, you'll need to visit each submodule directory to checkout
  82 specific branches. Here, we'll check out the master branch of each submodule:
  83
  84 .. code:: bash
  85
  86    git submodule foreach 'git checkout master'
  87
  88 You might find that changes upstream have occurred since you cloned the
  89 submodules. To pull in the latest changes:
  90
  91 .. code:: bash
  92
  93    git submodule foreach 'git pull'
  94
  95 Finally, for every submodule, you'll have to tell git-review how to find
  96 Gerrit.
  97
  98 .. code:: bash
  99
 100    cd doc # Make sure we're in the top level doc repo directory
 101    git submodule foreach 'REPO=$(echo $path | sed "s/docs\/submodules\///") ; git remote add gerrit ssh://<LFID>@gerrit.onap.org:29418/$REPO'
 102
 103 Or, if you prefer to do only one at a time:
 104
 105 .. code:: bash
 106
 107    git remote add gerrit ssh://<LFID>@gerrit.onap.org:29418/repopath/repo.git
 108
 109 Requesting Reviews
 110 ------------------
 111
 112 The benefit of working with submodules in this way is that now you can
 113 make changes, do commits, and request reviews within the submodule
 114 directory just as if you had cloned the repository in its own directory.
 115
 116 So, you commit as normal, with :code:`git commit -s`, and review as
 117 normal with :code:`git review`.