This page is a guide to getting started hacking on Buildbot.

Local Setup

First, get virtualenv installed. You'll need to install this in your system's site-packages, but it's easy. If your package manager provides a way to do this, use it instead.

sudo easy_install virtualenv

Set yourself up a working directory with a sandbox and some source

mkdir ~/buildbot-work
cd ~/buildbot-work
git clone -o upstream git:// src
virtualenv sandbox

Activate the sandbox

source sandbox/bin/activate      # UNIX
source sandbox/Scripts/activate  # Windows

You should see a (sandbox) prefixed to your shell prompt. Install buildbot with the 'develop' option so that you can hack on the active code

cd src
pip install -e master
pip install -e worker

Install a few additional tools only required for development:

pip install mock sphinx pyflakes

The Source

Have a look around in src/. You'll find all of the code for the buildmaster under master/, and likewise for worker/. Docs are under master/docs in reStructuredText format, which is pretty intuitive. Unit tests are located under master/test/unit, in a file named after the file they're testing, e.g., master/buildbot/process/ is tested by master/buildbot/test/unit/ Run the unit tests now, just to make sure you're starting from a solid base of passing tests:

trial buildbot.test buildbot_worker.test

Note that you can also run pyflakes master/buildbot to detect any small Python syntax issues.

Before you get started making changes, check out a git branch named after what you're working on. This can be bug1234 or new-cool-stuff or whatever you'd like -- just avoid master.

git checkout -b new-cool-stuff upstream/master  # if you're working on Buildbot-0.9.x, or
git checkout -b new-cool-stuff upstream/eight   # if you're working on Buildbot-0.8.x

Git makes it easy to have multiple branches in the same repository and switch between them, but that's getting ahead of things for now.

Hack away! Pull requests need tests for any new code, documentation, and an update to the release notes (master/docs/relnotes/index.rst) for most changes. See SubmittingPatches for the full list of requirements.

Git and Pull Requests

Once your patch is complete, it's time to commit it. First, a little one-time setup for Github. The short story is that there are *three* Github repositories involved: your local repository, your fork on github (, and the "upstream" Buildbot repository (

Make a Github account if you don't have one. Navigate to the Buildbot repository and click the "fork" button. This will create your fork on Github. Copy the SSH URL from the Github page (something like, and substitute it into the following:

git remote add origin

Now, back to your patch. Run git status to make sure that only the files you want have been changed. Run git branch to make sure you're on the right branch. Run git add . to add everything, and then run git diff --cached to get a preview of the patch. If everything looks OK, run git commit to commit it locally.

Once that's in shape, run git push origin <branchname> to push the changes to your Github repository. Use the same branch name as you used locally. Then open your repository up in your browser ( and you will see your branch with a "Pull Request" button next to it. Click that button. IMPORTANT: if you're working on Buildbot-0.8.x, tell Github that the pull is against base branch 'eight', or your pull request will include a lot more commits than you want. Type a nice message describing the patch to the people who will be reviewing it.

The reviewers may ask you to make some additional changes. The easiest way to do so is to make the requested changes and repeat the part above with git status, git branch, etc. Don't forget to make sure the tests still pass! Once your patch is accepted, you're done!

Buildbot developers are always happy to help with this process - just ask!

Last modified 14 months ago Last modified on Jan 4, 2017, 1:57:28 AM