update documentation for the change

* move parameter description to cfg-statustargets.rst * update examples/{git,repo}_gerrit.cfg to match the expected callback result * user git_gerrit.cfg as a source for examples, instead of putting a huge example text in the cfg-statustargets.rst * update release notes
buildbot · Jul 11, 2014 · e0be6c9 · e0be6c9
1 parent 0b1826e
commit e0be6c9
Show file tree

Hide file tree

Showing 5 changed files with 110 additions and 80 deletions.
diff --git a/master/buildbot/status/status_gerrit.py b/master/buildbot/status/status_gerrit.py
@@ -135,20 +135,6 @@ class GerritStatusPush(StatusReceiverMultiService, buildset.BuildSetSummaryNotif
     def __init__(self, server, username, reviewCB=DEFAULT_REVIEW,
                  startCB=None, port=29418, reviewArg=None,
                  startArg=None, summaryCB=DEFAULT_SUMMARY, summaryArg=None, **kwargs):
-        """
-        @param server:    Gerrit SSH server's address to use for push event notifications.
-        @param username:  Gerrit SSH server's username.
-        @param reviewCB:  Callback that is called each time a build is finished, and that is used
-                          to define the message and review approvals depending on the build result.
-        @param startCB:   Callback that is called each time a build is started.
-                          Used to define the message sent to Gerrit.
-        @param port:      Gerrit SSH server's port.
-        @param reviewArg: Optional argument passed to the review callback.
-        @param startArg:  Optional argument passed to the start callback.
-        @param summaryCB:  Callback that is called each time a buildset finishes, and that is used
-                           to define a message and review approvals depending on the build result.
-        @param summaryArg: Optional argument passed to the summary callback.
-        """
         StatusReceiverMultiService.__init__(self)
 
         # If neither reviewCB nor summaryCB were specified, default to sending

diff --git a/master/docs/examples/git_gerrit.cfg b/master/docs/examples/git_gerrit.cfg
@@ -145,7 +145,7 @@ from buildbot.status.builder import Results, SUCCESS, RETRY
 
 def gerritReviewCB(builderName, build, result, status, arg):
     if result == RETRY:
-        return None, 0, 0
+        return dict()
 
     message =  "Buildbot finished compiling your patchset\n"
     message += "on configuration: %s\n" % builderName
@@ -155,8 +155,10 @@ def gerritReviewCB(builderName, build, result, status, arg):
         message += "\nFor more details visit:\n"
         message += status.getURLForThing(build) + "\n"
 
-    # message, verified, reviewed
-    return message, (result == SUCCESS or -1), 0
+    return dict(message=message,
+                labels={
+                    'Verified': 1 if result == SUCCESS or -1
+                })
 
 def gerritStartCB(builderName, build, arg):
     print "gerritStartCB..."
@@ -192,8 +194,10 @@ def gerritSummaryCB(buildInfoList, results, status, arg):
     else:
         verified = -1
 
-    reviewed = 0
-    return (msg, verified, reviewed)
+    return dict(message=message,
+                labels={
+                    'Verified': verified
+                })
 
 c['buildbotURL'] = 'http://buildbot.example.com/'
 c['status'].append(GerritStatusPush(gerrit_url, gerrit_user,

diff --git a/master/docs/examples/repo_gerrit.cfg b/master/docs/examples/repo_gerrit.cfg
@@ -148,7 +148,7 @@ def gerritMessageCB(buildername, build, results):
     message += "the result is %s\n"%(Results[results])
     message += sep
     message += "more details %s/builders/%s/builds/%d\n"%(c['buildbotURL'],buildername,build.getNumber())
-    return message,0,0
+    return dict(message=message)
 c['status'].append(GerritStatusPush(gerrit_server,gerrit_user,gerritMessageCB))
 
 ## PROJECT IDENTITY

diff --git a/master/docs/manual/cfg-statustargets.rst b/master/docs/manual/cfg-statustargets.rst
@@ -973,85 +973,90 @@ GerritStatusPush
 :class:`GerritStatusPush` sends review of the :class:`Change` back to the Gerrit server,
 optionally also sending a message when a build is started. GerritStatusPush
 can send a separate review for each build that completes, or a single review
-summarizing the results for all of the builds. By default, a single summary
-review is sent; that is, a default summaryCB is provided, but no reviewCB or
-startCB.
+summarizing the results for all of the builds.
 
-``reviewCB``, if specified, determines the message and score to give when
-sending a review for each separate build. It should return a tuple of
-(message, verified, reviewed).
+.. py:class:: GerritStatusPush(server, username, reviewCB, startCB, port, reviewArg, startArg, summaryCB, summaryArg, ...)
 
-If ``startCB`` is specified, it should return a message. This message will be
-sent to the Gerrit server when each build is started.
+   :param string server: Gerrit SSH server's address to use for push event notifications.
+   :param string username: Gerrit SSH server's username.
+   :param int port: (optional) Gerrit SSH server's port (default: 29418)
+   :param reviewCB: (optional) callback that is called each time a build is
+                    finished, and that is used to define the message and review
+                    approvals depending on the build result.
 
-``summaryCB``, if specified, determines the message and score to give when
-sending a single review summarizing all of the builds. It should return a
-tuple of (message, verified, reviewed).
+   :param reviewArg: (optional) argument passed to the review callback.
 
-::
+                    If :py:func:`reviewCB` callback is specified, it determines
+                    the message and score to give when sending a review for
+                    each separate build. It should return a dictionary:
+
+                    .. code-block:: python
+
+                        {'message': message,
+                         'labels': {label-name: label-score,
+                                    ...}
+                        }
+
+                    For example:
+
+                    .. literalinclude:: /examples/git_gerrit.cfg
+                       :pyobject: gerritReviewCB
+                       :language: python
 
-    from buildbot.status.status_gerrit import GerritStatusPush
-    from buildbot.status.builder import Results, SUCCESS, RETRY
+                    Where ``Results``, ``RETRY`` and ``SUCCESS`` are imported like
 
-    def gerritReviewCB(builderName, build, result, status, arg):
-        if result == RETRY:
-            return None, 0, 0
+                    .. code-block:: python
 
-        message =  "Buildbot finished compiling your patchset\n"
-        message += "on configuration: %s\n" % builderName
-        message += "The result is: %s\n" % Results[result].upper()
+                       from buildbot.status.builder import Results, SUCCESS, RETRY
 
-        if arg:
-            message += "\nFor more details visit:\n"
-            message += status.getURLForThing(build) + "\n"
+   :param startCB: (optional) callback that is called each time a build is
+                   started.  Used to define the message sent to Gerrit.
+   :param startArg: (optional) argument passed to the start callback.
 
-        # message, verified, reviewed
-        return message, (result == SUCCESS or -1), 0
+                    If :py:func:`startCB` is specified, it should return a
+                    message. This message will be sent to the Gerrit server
+                    when each build is started, for example:
 
-    def gerritStartCB(builderName, build, arg):
-        message = "Buildbot started compiling your patchset\n"
-        message += "on configuration: %s\n" % builderName
+                    .. literalinclude:: /examples/git_gerrit.cfg
+                       :pyobject: gerritStartCB
 
-        return message
+   :param summaryCB: (optional) callback that is called each time a buildset
+                     finishes, and that is used to define a message and review
+                     approvals depending on the build result.
+   :param summaryArg: (optional) argument passed to the summary callback.
 
-    def gerritSummaryCB(buildInfoList, results, status, arg):
-        success = False
-        failure = False
+                      If :py:func:`summaryCB` callback is specified, determines
+                      the message and score to give when sending a single
+                      review summarizing all of the builds. It should return a
+                      dictionary:
 
-        msgs = []
+                      .. code-block:: python
 
-        for buildInfo in buildInfoList:
-            msg = "Builder %(name)s %(resultText)s (%(text)s)" % buildInfo
-            link = buildInfo.get('url', None)
-            if link:
-                msg += " - " + link
-            else:
-                msg += "."
-            msgs.append(msg)
+                          {'message': message,
+                           'labels': {label-name: label-score,
+                                      ...}
+                          }
 
-            if buildInfo['result'] == SUCCESS:
-                success = True
-            else:
-                failure = True
+                      .. literalinclude:: /examples/git_gerrit.cfg
+                         :pyobject: gerritSummaryCB
 
-        msg = '\n\n'.join(msgs)
+.. note::
+
+   By default, a single summary review is sent; that is, a default
+   :py:func:`summaryCB` is provided, but no :py:func:`reviewCB` or
+   :py:func:`startCB`.
+
+.. note::
 
-        if success and not failure:
-            verified = 1
-        else:
-            verified = -1
+   If :py:func:`reviewCB` or :py:func:`summaryCB` do not return any labels,
+   only a message will be pushed to the Gerrit server.
 
-        reviewed = 0
-        return (msg, verified, reviewed)
+.. seealso::
 
-    c['buildbotURL'] = 'http://buildbot.example.com/'
-    c['status'].append(GerritStatusPush('127.0.0.1', 'buildbot',
-                                        reviewCB=gerritReviewCB,
-                                        reviewArg=c['buildbotURL'],
-                                        startCB=gerritStartCB,
-                                        startArg=c['buildbotURL'],
-                                        summaryCB=gerritSummaryCB,
-                                        summaryArg=c['buildbotURL']))
+   :file:`master/docs/examples/git_gerrit.cfg` and
+   :file:`master/docs/examples/repo_gerrit.cfg` in the Buildbot distribution
+   provide a full example setup of Git+Gerrit or Repo+Gerrit of
+   :bb:status:`GerritStatusPush`.
 
 .. bb:status:: GitHubStatus
 

diff --git a/master/docs/relnotes/index.rst b/master/docs/relnotes/index.rst
@@ -70,6 +70,41 @@ Fixes
   build are overwitten. This both ensures more consistent builds and avoids
   errors when updating submodules.
 
+* Buildbot is now compatible with Gerrit v2.6 and higher.
+
+  To make this happen, the return result of ``reviewCB`` and ``summaryCB``
+  callback has changed from
+
+  .. code-block:: python
+
+     (message, verified, review)
+
+  to
+
+  .. code-block:: python
+
+     {'message': message,
+      'labels': {'label-name': value,
+                ...
+                }
+     }
+
+  The implications are:
+
+  * there are some differences in behaviour: only those labels that were
+    provided will be updated
+  * Gerrit server must be able to provide a version, if it can't the
+    :bb:status:`GerritStatusPush` will not work
+
+  .. note::
+
+     If you have an old style ``reviewCB`` and/or ``summaryCB`` implemented,
+     these will still work, however there could be more labels updated than
+     anticipated.
+
+  More detailed information is available in :bb:status:`GerritStatusPush`
+  section.
+
 Deprecations, Removals, and Non-Compatible Changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~