Appendix Gerrit Topics

Additional detail regarding Gerrit Topics and 3 ways to push
them depending on preference.

Issue: https://jira.opendaylight.org/browse/DOCS-21
Change-Id: Ia257a1a5a08aaf3ed13612316b424f16bd197e4d
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

diff --git a/docs/gerrit.rst b/docs/gerrit.rst
index 8feca45..e9465b4 100644 (file)
--- a/docs/gerrit.rst
+++ b/docs/gerrit.rst
@@ -215,8 +215,10 @@ if possible as it makes working with Gerrit much easier.
 
       git review
 
-   We can optionally pass the parameter ``-t my_topic`` to set a topic in
-   Gerrit. Useful when we have related patches to organize in one topic.
+   We can optionally pass the parameter ``-t my_topic`` to set a
+   :ref:`topic <gerrit-topics>` in
+   Gerrit. Useful when we have related patches to organize in one
+   :ref:`topic <gerrit-topics>`.
 
 Once pushed we should see some output in the terminal as described in
 :ref:`Gerrit Push Output <gerrit-push-output>`.
@@ -676,3 +678,31 @@ author of the code which indicates that they have read and agree to the DCO.
    :name: dco
 
 Refer to https://developercertificate.org/ for original text.
+
+.. _gerrit-topics:
+
+Gerrit Topics
+-------------
+
+Topics are useful as a search criteria in Gerrit. By entering ``topic:foo``
+as a search criteria we can track related commits. Use one of the following
+methods to configure topics:
+
+1. Directly in the Gerrit UI via the Edit Topic button
+2. Via ``git review`` using the ``-t topic`` parameter
+
+   .. note::
+
+      git-review defaults to the local branch name as the topic if it does not
+      match the upstream branch.
+
+3. Via ``git push`` using one of the following methods:
+
+   .. code-block:: bash
+
+      git push origin HEAD:refs/for/master%topic=some-topic
+      git push origin HEAD:refs/for/master -o topic=some-topic
+
+   Both methods achieve the same result so is up to preference. Further
+   documentation available at `Gerrit Topics
+   <https://gerrit-review.googlesource.com/Documentation/intro-user.html#topics>`_.