Updates and Review

NOTE: THIS SECTION IS UNDER HEAVY DEVELOPMENT USE WITH CAUTION

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 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 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 directions for building the entire documentation tree 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:

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:

git submodule foreach 'git pull'

Finally, for every submodule, you’ll have to tell git-review how to find Gerrit.

cd doc # Make sure we're in the top level doc repo directory
git submodule foreach 'REPO=$(echo $path | sed "s/docs\/submodules\///") ; git remote add gerrit ssh://<LFID>@gerrit.onap.org:29418/$REPO'

Or, if you prefer to do only one at a time:

git remote add gerrit ssh://<LFID>@gerrit.onap.org:29418/repopath/repo.git

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 git commit -s, and review as normal with git review.