Custom parameter function takes QueueItem

With the change to use QueueItem, the custom parameter function
has lost some context.  Pass a QueueItem instead of a Change in
order to get it back.

Add the parameters to the build object so that they can be used
by URL pattern functions.

Add a NEWS.rst file that lists backwards incompatible changes (of
which this is one).

Change-Id: I526850fb55e25b4b84202820dc3c313d37cbe535
Reviewed-on: https://review.openstack.org/36304
Reviewed-by: Jeremy Stanley <fungi@yuggoth.org>
Reviewed-by: Clark Boylan <clark.boylan@gmail.com>
Approved: James E. Blair <corvus@inaugust.com>
Tested-by: Jenkins

NEWS.rst

@@ -0,0 +1,13 @@
+Since 1.2.0:
+
+* The Jenkins launcher is replaced with Gearman launcher.  An internal
+  Gearman server is provided, and there is a Gearman plugin for
+  Jenkins, so migration to the new system should be fairly
+  straightforward.  See the Launchers section of the documentation for
+  details.
+
+* The custom parameter function signature now takes a QueueItem as the
+  first argument, rather than the Change.  The QueueItem has the full
+  context for why the change is being run (including the pipeline,
+  items ahead and behind, etc.).  The Change is still available via
+  the "change" attribute on the QueueItem.

doc/source/zuul.rst

@@ -459,15 +459,15 @@ each job as it builds a list from the project specification.
   included with the :ref:`includes` directive.  The function
   should have the following signature:
 
-  .. function:: parameters(change, parameters)
+  .. function:: parameters(item, parameters)
 
      Manipulate the parameters passed to a job before a build is
      launched.  The ``parameters`` dictionary will already contain the
      standard Zuul job parameters, and is expected to be modified
      in-place.
 
-     :param change: the current change
-     :type change: zuul.model.Change
+     :param item: the current queue item
+     :type item: zuul.model.QueueItem
      :param parameters: parameters to be passed to the job
      :type parameters: dict
 

tests/fixtures/custom_functions.py

@@ -1,2 +1,2 @@
-def select_debian_node(change, params):
+def select_debian_node(item, params):
     params['ZUUL_NODE'] = 'debian'

zuul/launcher/gearman.py

@@ -274,7 +274,7 @@ class Gearman(object):
         # ZUUL_SHORT_OLDREV
 
         if callable(job.parameter_function):
-            job.parameter_function(item.change, params)
+            job.parameter_function(item, params)
             self.log.debug("Custom parameter function used for job %s, "
                            "change: %s, params: %s" % (job, item.change,
                                                        params))
@@ -284,6 +284,7 @@ class Gearman(object):
         else:
             name = "build:%s" % job.name
         build = Build(job, uuid)
+        build.parameters = params
 
         gearman_job = gear.Job(name, json.dumps(params),
                                unique=uuid)

zuul/model.py

@@ -465,6 +465,7 @@ class Build(object):
         self.launch_time = time.time()
         self.start_time = None
         self.end_time = None
+        self.parameters = {}
         self.fraction_complete = None
 
     def __repr__(self):