[Buildbot-devel] Documentation inconsistency in Git Source Checkout?

[Jonathan Martens]

It seems there is a documentation inconsistency in the BuildBot 
documentation regarding the Git

The documentation reads (http://buildbot.net/buildbot/docs/latest/Git.html):

...
method
     Git's incremental mode does not require a method. The full mode has 
four methods defined:

     clobber
         It removes the build directory entirely then makes full clone 
from repo. This can be slow as it need to clone whole repository
     fresh
         This remove all other files except those tracked by Git. First 
it does git clean -d -f -x then fetch/checkout to a specified 
revision(if any). This option is equal to update mode with 
ignore_ignores=True in old steps.
     clean
         All the files which are tracked by Git and listed ignore files 
are not deleted. Remaining all other files will be deleted before 
fetch/checkout. This is equivalent to git clean -d -f then fetch. This 
is equivalent to ignore_ignores=False in old steps.
     copy
         This first checkout source into source directory then copy the 
source directory to build directory then performs the build operation in 
the copied directory. This way we make fresh builds with very less 
bandwidth to download source. The behavior of source checkout follows 
exactly same as incremental. It performs all the incremental checkout 
behavior in source directory.
...

But when I set the method to 'fresh' and check my configuration file it 
bails out with the following error:

	Traceback (most recent call last):
	  File "D:\virtualenv\buildbot\lib\site-packages\buildbot\master.py", 
line 194, in loadTheConfigFile
	    d = self.loadConfig(f)
	  File "D:\virtualenv\buildbot\lib\site-packages\buildbot\master.py", 
line 547, in loadConfig
	    d.addCallback(do_load)
	  File 
"D:\virtualenv\buildbot\lib\site-packages\twisted\internet\defer.py", 
line 297, in addCallback
	    callbackKeywords=kw)
	  File 
"D:\virtualenv\buildbot\lib\site-packages\twisted\internet\defer.py", 
line 286, in addCallbacks
	    self._runCallbacks()
	--- <exception caught here> ---
	  File 
"D:\virtualenv\buildbot\lib\site-packages\twisted\internet\defer.py", 
line 542, in _runCallbacks
	    current.result = callback(current.result, *args, **kw)
	  File "D:\virtualenv\buildbot\lib\site-packages\buildbot\master.py", 
line 223, in do_load
	    exec f in localDict
	  File "D:\buildbot-data\master\master.cfg", line 70, in <module>
	    mode='fresh'
	  File 
"D:\virtualenv\buildbot\lib\site-packages\buildbot\steps\source.py", 
line 831, in __init__
	    Source.__init__(self, **kwargs)
	  File 
"D:\virtualenv\buildbot\lib\site-packages\buildbot\steps\source.py", 
line 167, in __init__
	    assert mode in ("update", "copy", "clobber", "export")
	exceptions.AssertionError:

It seems the only allowed methods are called "update", "copy", "clobber" 
and "export" where the documentations mentions "clobber", "fresh", 
"clean" and "copy".

Apart from that it seems that a parameter is missing documentation as 
mode does not have a description:

...
clobberOnFailure
     (optional): defaults to False. If a fetch or full clone fails we 
can checkout source removing everything. This way new repository will be 
cloned. If retry fails it fails the source checkout step.
mode
method
...

The above seems to be present for the general Source Checkout page as 
well as http://buildbot.net/buildbot/docs/latest/Source-Checkout.html 
looks like this:

...
Parameters

All source checkout steps accept some common parameters to control how 
they get the sources and where they should be placed. The remaining 
per-VC-system parameters are mostly to specify where exactly the sources 
are coming from.

mode
method
     These two parameters specify the means by which the source is 
checked out. mode specifies the type of checkout and method tells about 
the way to implement it.
...

Kind regards,

Jonathan