Merge remote-tracking branch 'origin/buildbot-0.8.8' into buildbot-0.8.8

master/buildbot/process/factory.py

@@ -87,25 +87,25 @@ def __init__(self, source, configure="./configure",
             else:
                 assert isinstance(configure, (list, tuple))
                 command = configure + configureFlags
-            self.addStep(Configure, command=command, env=configureEnv)
+            self.addStep(Configure(command=command, env=configureEnv))
         if compile is not None:
-            self.addStep(Compile, command=compile)
+            self.addStep(Compile(command=compile))
         if test is not None:
-            self.addStep(Test, command=test)
+            self.addStep(Test(command=test))
 
 class CPAN(BuildFactory):
     def __init__(self, source, perl="perl"):
         BuildFactory.__init__(self, [source])
-        self.addStep(Configure, command=[perl, "Makefile.PL"])
-        self.addStep(Compile, command=["make"])
-        self.addStep(PerlModuleTest, command=["make", "test"])
+        self.addStep(Configure(command=[perl, "Makefile.PL"]))
+        self.addStep(Compile(command=["make"]))
+        self.addStep(PerlModuleTest(command=["make", "test"]))
 
 class Distutils(BuildFactory):
     def __init__(self, source, python="python", test=None):
         BuildFactory.__init__(self, [source])
-        self.addStep(Compile, command=[python, "./setup.py", "build"])
+        self.addStep(Compile(command=[python, "./setup.py", "build"]))
         if test is not None:
-            self.addStep(Test, command=test)
+            self.addStep(Test(command=test))
 
 class Trial(BuildFactory):
     """Build a python module that uses distutils and trial. Set 'tests' to
@@ -137,15 +137,15 @@ def __init__(self, source,
 
         from buildbot.steps.python_twisted import Trial
         buildcommand = buildpython + ["./setup.py", "build"]
-        self.addStep(Compile, command=buildcommand, env=env)
-        self.addStep(Trial,
+        self.addStep(Compile(command=buildcommand, env=env))
+        self.addStep(Trial(
                      python=trialpython, trial=self.trial,
                      testpath=testpath,
                      tests=tests, testChanges=useTestCaseNames,
                      randomly=self.randomly,
                      recurse=self.recurse,
                      env=env,
-                     )
+                     ))
 
 
 # compatibility classes, will go away. Note that these only offer

master/docs/developer/cls-forcesched.rst

@@ -21,34 +21,50 @@ new parameter types or hacking the existing types.
    This is the base implementation for most parameters, it will check validity,
    ensure the arg is present if the :py:attr:`~IParameter.required` attribute
    is set, and implement the default value.  It will finally call
-   :py:meth:`~IParameter.update_from_post` to process the string(s) from the
+   :py:meth:`~IParameter.updateFromKwargs` to process the string(s) from the
    HTTP POST.
 
-   This class implements :py:class:`IParameter`, and subclasses are expected to
-   adhere to that interface.
-
-   The :py:class:`BaseParameter` constructor converts any keyword arguments
+   The :py:class:`BaseParameter` constructor converts all keyword arguments
    into instance attributes, so it is generally not necessary for subclasses to
    implement a constructor.
 
-    .. py:method:: update_from_post(master, properties, changes, req)
+   For custom parameters that set properties, one simple customization point 
+   is `getFromKwargs`: 
+
+    .. py:method:: getFromKwargs(kwargs)
+
+        :param kwargs: a dictionary of the posted values
+
+        Given the passed-in POST parameters, return the value of the property
+        that should be set.
+
+   For more control over parameter parsing, including modifying sourcestamps or
+   changeids, override the ``updateFromKwargs`` function, which is the function
+   that :py:class:`ForceScheduler` invokes for processing:
+
+    .. py:method:: updateFromKwargs(master, properties, changes, sourcestamps, kwargs)
 
         :param master: the :py:class:`~buildbot.master.BuildMaster` instance
         :param properties: a dictionary of properties
         :param changes: a list of changeids that will be used to build the
             SourceStamp for the forced builds
-        :param req: the Twisted Web request object
+        :param sourcestamps: the SourceStamp dictionary that will be passed to the 
+            build; some parameters modify sourcestamps rather than properties.
+        :param kwargs: a dictionary of the posted values
+
+        This method updates ``properties``, ``changes``,  and/or ``sourcestamps``
+        according to the request.  The default implementation is good for many simple 
+        uses, but can be overridden for more complex purposes.
 
-        This method updates ``properties`` and/or ``changes`` according to the
-        request.  The default implementation is good for many simple uses, but
-        can be overridden for more complex purposes.
+        When overriding this function, take all parameters by name (not by position),
+        and include an ``**unused`` catch-all to guard against future changes.
 
     The remaining attributes and methods should be overridden by subclasses, although
     :py:class:`BaseParameter` provides appropriate defaults.
 
     .. py:attribute:: name
 
-           The name of the parameter. This will correspond to the name of the
+           The name of the parameter. This corresponds to the name of the
            property that your parameter will set.  This name is also used
            internally as identifier for http POST arguments
 
@@ -57,16 +73,23 @@ new parameter types or hacking the existing types.
            The label of the parameter, as displayed to the user.  This value
            can contain raw HTML.
 
+    .. py:method:: fullName
+
+           A fully-qualified name that uniquely identifies the parameter in the
+           scheduler.  This name is used internally as the identifier for HTTP
+           POST arguments. It is a mix of `name` and the parent's `name` (in the 
+           case of nested parameters). This field is not modifiable.
+
     .. py:attribute:: type
 
-           The type of the parameter is used by the jinja template to create
-           appropriate html form widget.  The available values are visible in
-           :bb:src:`master/buildbot/status/web/template/forms.html` in the
-           ``force_build_one_scheduler`` macro.
+           A list of types that the parameter conforms to. These are used by the 
+           jinja template to create appropriate html form widget.  The available 
+           values are visible in :bb:src:`master/buildbot/status/web/template/forms.html` 
+           in the ``force_build_one_scheduler`` macro.
 
     .. py:attribute:: default
 
-           The default value, used if there is no user input.  This is also
+           The default value to use if there is no user input.  This is also
            used to fill in the form presented to the user.
 
     .. py:attribute:: required
@@ -76,7 +99,7 @@ new parameter types or hacking the existing types.
 
     .. py:attribute:: multiple
 
-           If true, this parameter will return a list of values (e.g. list of
+           If true, this parameter represents a list of values (e.g. list of
            tests to run)
 
     .. py:attribute:: regex
@@ -97,3 +120,34 @@ new parameter types or hacking the existing types.
        default function will just return the unmodified string
 
 
+Nested Parameters
+~~~~~~~~~~~~~~~~~
+
+The :py:class:`NestedParameter` class is a container for parameters. The motivating purpose for this feature
+is the multiple-codebase configuration, which needs to provide the user with a form to control
+the branch (et al) for each codebase independently. Each branch parameter is a string field with name 
+'branch' and these must be disambiguated.
+
+Each of the child parameters mixes in the parent's name to create the fully qualified ``fullName``. This 
+allows, for example, each of the 'branch' fields to have a unique name in the POST request. The 
+`NestedParameter` handles adding this extra bit to the name to each of the children. When the `kwarg` 
+dictionary is posted back, this class also converts the flat POST dictionary into a richer structure 
+that represents the nested structure. 
+
+As illustration, if the nested parameter has the name 'foo', and has children 'bar1' and 'bar2', then the
+POST will have entries like "foo-bar1" and "foo-bar2". The nested parameter will translate this into a 
+dictionary in the 'kwargs' structure, resulting in something like::
+
+    kwargs = { 
+        # ...
+        'foo': {
+            'bar1': '...', 
+            'bar2': '...' 
+        }
+    }
+
+Arbitrary nesting is allowed and results in a deeper dictionary structure. 
+
+Nesting can also be used for presentation purposes. If the name of the :py:class:`NestedParameter` is empty, the
+nest is "anonymous" and does not mangle the child names. However, in the HTML layout, the nest
+will be presented as a logical group.

master/docs/manual/cfg-statustargets.rst

@@ -1161,8 +1161,8 @@ status objects:
 Name of the builder that generated this event
     ``name``
 
-Name of the project
-    :meth:`master_status.getProjectName()`
+Title of the buildmaster
+    :meth:`master_status.getTitle()`
 
 MailNotifier mode
     ``mode`` (a combination of ``change``, ``failing``, ``passing``, ``problem``, ``warnings``,

master/docs/relnotes/index.rst

@@ -73,6 +73,8 @@ Features
 * Master-side support for P4 is available, and provides a great deal more flexibility than the old slave-side step.
   See :bb:pull:`596`.
 
+* Builder configurations can now include a ``description``, which will appear in the web UI to help humans figure out what the builder does.
+
 Deprecations, Removals, and Non-Compatible Changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -131,7 +133,7 @@ Details
 For a more detailed description of the changes made in this version, see the
 git log itself::
 
-   git log v0.8.7..master
+   git log v0.8.7..v0.8.8
 
 Older Versions
 --------------

master/setup.py

@@ -120,6 +120,7 @@ def make_release_tree(self, base_dir, files):
     'packages': ["buildbot",
               "buildbot.status", "buildbot.status.web","buildbot.status.web.hooks",
               "buildbot.changes",
+              "buildbot.buildslave",
               "buildbot.steps",
               "buildbot.steps.package",
               "buildbot.steps.package.deb",