From b6dc6bd6cf0adb4d34c01f85a33824e8136e9903 Mon Sep 17 00:00:00 2001
From: Jacob Stultz <jstultz@alum.mit.edu>
Date: Wed, 1 Aug 2012 12:16:50 -0700
Subject: [PATCH] Add start callback to GerritStatusPush docs

Documentation updated, and mentioned in release notes.
---
 master/docs/manual/cfg-statustargets.rst | 18 ++++++++++++++++--
 master/docs/release-notes.rst            |  2 ++
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/master/docs/manual/cfg-statustargets.rst b/master/docs/manual/cfg-statustargets.rst
index 17eecd83747..3450aca2957 100644
--- a/master/docs/manual/cfg-statustargets.rst
+++ b/master/docs/manual/cfg-statustargets.rst
@@ -1461,14 +1461,28 @@ GerritStatusPush
         # message, verified, reviewed
         return message, (result == SUCCESS or -1), 0
 
+    def gerritStartCB(builderName, build, arg):
+        message = "Buildbot started compiling your patchset\n"
+        message += "on configuration: %s\n" % builderName
+
+        if arg:
+            message += "\nFor more details visit:\n"
+            message += status.getURLForThing(build) + "\n"
+
+        return message
+
     c['buildbotURL'] = 'http://buildbot.example.com/'
     c['status'].append(GerritStatusPush('127.0.0.1', 'buildbot',
                                         reviewCB=gerritReviewCB,
-                                        reviewArg=c['buildbotURL']))
+                                        reviewArg=c['buildbotURL'],
+                                        startCB=gerritStartCB,
+                                        startArg=c['buildbotURL']))
 
-GerritStatusPush sends review of the :class:`Change` back to the Gerrit server.
+GerritStatusPush sends review of the :class:`Change` back to the Gerrit server,
+optionally also sending a message when a build is started.
 ``reviewCB`` should return a tuple of message, verified, reviewed. If message
 is ``None``, no review will be sent.
+``startCB`` should return a message.
 
 .. [#] Apparently this is the same way http://buildd.debian.org displays build status
 
diff --git a/master/docs/release-notes.rst b/master/docs/release-notes.rst
index 1502679244a..9d63d9da2c4 100644
--- a/master/docs/release-notes.rst
+++ b/master/docs/release-notes.rst
@@ -122,6 +122,8 @@ Features
   to render a nice Login link in WebStatus for unauthenticated users if
   ``useHttpHeader`` and ``httpLoginUrl`` are set.
 
+* Added an optional build start callback to ``buildbot.status.status_gerrit.GerritStatusPush``
+
 Slave
 -----