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. 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 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, 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.
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.