diff options
Diffstat (limited to 'docs/guides/onap-developer/how-to-use-docs')
| -rw-r--r-- | docs/guides/onap-developer/how-to-use-docs/update-review.rst | 136 |
1 files changed, 34 insertions, 102 deletions
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 index eb4228da7..3c3a0c037 100644 --- a/docs/guides/onap-developer/how-to-use-docs/update-review.rst +++ b/docs/guides/onap-developer/how-to-use-docs/update-review.rst @@ -5,113 +5,45 @@ 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 :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: +Updates +------- + +#. Create a JIRA task in the `ONAP JIRA <https://jira.onap.org/>`_ +before you start the updates. The created issue's ID will have to be added to +the commit message. + +.. note:: + The task should be created in the affected project's workspace. The release + should be specified, as well. + +#. If you have not cloned the repository yet, follow the instructions in the +Git guide, section Cloning a repository. If you have done so already, pull the +latest version. +#. Create a local git branch for your changes. +#. Update the required documents in the project repo(s). +#. Build the documentation with tox. +#. Check the output for errors. +#. Add the changed files. +#. Commit your changes. In the commit message, include the issue ID of the +JIRA task, e.g. Issue-ID:DOC-602 +#. Request review with git review. -.. 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' - -Finally, for every submodule, you'll have to tell git-review how to find -Gerrit. - -.. code:: bash - - 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: - -.. code:: bash - - 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 :code:`git commit -s`, and review as -normal with :code:`git review`. +#. Go to the gerrit review's page included in the output of the git review +command. +#. In gerrit, add the committers for the given +project. For more information, refer to the `Gerrit guide <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html#review>`_. + +#. Implement comments by updating your patch, based on +`Updating an existing patch <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html#update-an-existing-patch>`_ +in the Gerrit guide. + +.. note:: + If you already have the branch you need, skip the first 2 steps in the above + guide. |