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