Previous: How Different VC Systems Specify Sources, Up: Version Control Systems

3.1.4 Attributes of Changes


Each Change has a who attribute, which specifies which developer is responsible for the change. This is a string which comes from a namespace controlled by the VC repository. Frequently this means it is a username on the host which runs the repository, but not all VC systems require this (Arch, for example, uses a fully-qualified Arch ID, which looks like an email address, as does Darcs). Each StatusNotifier will map the who attribute into something appropriate for their particular means of communication: an email address, an IRC handle, etc.


It also has a list of files, which are just the tree-relative filenames of any files that were added, deleted, or modified for this Change. These filenames are used by the fileIsImportant function (in the Scheduler) to decide whether it is worth triggering a new build or not, e.g. the function could use the following function to only run a build if a C file were checked in:

     def has_C_files(change):
         for name in change.files:
             if name.endswith(".c"):
                 return True
         return False

Certain BuildSteps can also use the list of changed files to run a more targeted series of tests, e.g. the python_twisted.Trial step can run just the unit tests that provide coverage for the modified .py files instead of running the full test suite.


The Change also has a comments attribute, which is a string containing any checkin comments.


A change's project, by default the empty string, describes the source code that changed. It is a free-form string which the buildbot administrator can use to flexibly discriminate among changes.

Generally, a project is an independently-buildable unit of source. This field can be used to apply different build steps to different projects. For example, an open-source application might build its Windows client from a separate codebase than its POSIX server. In this case, the change sources should be configured to attach an appropriate project string (say, "win-client" and "server") to changes from each codebase. Schedulers would then examine these strings and trigger the appropriate builders for each project.


A change occurs within the context of a specific repository. This is generally specified with a string, and for most version-control systems, this string takes the form of a URL.

Changes can be filtered on repository, but more often this field is used as a hint for the build steps to figure out which code to check out.


Each Change can have a revision attribute, which describes how to get a tree with a specific state: a tree which includes this Change (and all that came before it) but none that come after it. If this information is unavailable, the .revision attribute will be None. These revisions are provided by the ChangeSource, and consumed by the computeSourceRevision method in the appropriate source.Source class.

revision is an int, seconds since the epoch
revision is an int, the changeset number (r%d)
revision is a large string, the output of darcs changes --context
revision is a short string (a hash ID), the output of hg identify
revision is the full revision ID (ending in –patch-%d)
revision is an int, the transaction number
revision is a short string (a SHA1 hash), the output of e.g. git rev-parse


The Change might also have a branch attribute. This indicates that all of the Change's files are in the same named branch. The Schedulers get to decide whether the branch should be built or not.

For VC systems like CVS, Arch, Monotone, and Git, the branch name is unrelated to the filename. (that is, the branch name and the filename inhabit unrelated namespaces). For SVN, branches are expressed as subdirectories of the repository, so the file's “svnurl” is a combination of some base URL, the branch name, and the filename within the branch. (In a sense, the branch name and the filename inhabit the same namespace). Darcs branches are subdirectories of a base URL just like SVN. Mercurial branches are the same as Darcs.

branch='warner-newfeature', files=['src/foo.c']
branch='branches/warner-newfeature', files=['src/foo.c']
branch='warner-newfeature', files=['src/foo.c']
branch='warner-newfeature', files=['src/foo.c']
branch='buildbot–usebranches–0', files=['buildbot/']
branch='warner-newfeature', files=['src/foo.c']

Build Properties

A Change may have one or more properties attached to it, usually specified through the Force Build form or see sendchange. Properties are discussed in detail in the see Build Properties section.


Finally, the Change might have a links list, which is intended to provide a list of URLs to a viewcvs-style web page that provides more detail for this Change, perhaps including the full file diffs.