ALF/Build Server Use Case

First, a quick perspective on the purposes of a build system. Since that working group is not established, we'll try to incorporate the goals of Cruise Control, Anthill, OpenMake and others. We know some better than others and it isn't clear that this set of products should really be lumped together:

1. Execute Builds
2. Keep the Dev. Team notified of the quality of their builds.
3. Provide build trace-ability
4. Help manage releases
5. Provide build artifacts to interested parties

SCM use cases for Build systems

Get a project/component that needs to be built.

Fetch the source code and supporting files that comprise what needs to be built. This often involves creating a workspace and populating it.

Justification

In order to build, one needs the source.

Subtleties

1. It could involve several configurations. While in ClearCase, the config spec would fetch different modules from different VOBS, in BitKeeper it is more likely that several distinct configuration would be required.
2. We tend to view fetching a given configuration as it existed at a certain date or label as separate use cases, but that probably fits in to the more generic configuration.

Examples

• AccuRev - "mkws" followed by "update"
• Bitkeeper – "clone" followed by "get"
• ClearCase (Base) – "mkview" followed by "setcs"
• ClearCase (UCM) – "mkview" followed by "rebase"
• CVS – "checkout"
• Perforce – "sync"
• Subversion - "checkout"
• Version Manager - "get"

Update a workspace

Bring a workspace up to date with the latest changes relevant to its configuration.

Justification

To keep the developers aware of changes in the quality of their project, teams like to build as frequently as possible. Since full project checkouts are expensive, doing incremental updates for these builds is desirable.

Examples

• AccuRev - "update"
• Bitkeeper – "pull" followed by "get"
• ClearCase (Base) – dynamic views: no-op, snapshot views: "update"
• ClearCase (UCM) – "rebase"
• CVS – "update"
• Subversion - "update"
• Perforce – "sync"
• Version Manager - "get -u"

Get new versions since

Detect new versions in the elements in this workspace since a particular date (or baseline, etc, etc.).

Justification

Telling the team that the build status changed is useful. Informing the team who made changes and what they were is much better. Additionally, detecting changes between releases is useful.

In addition, a build system configured to do automated builds on a regular schedule may only want to build if there have been changes since the previous build using that configuration

Also, several build systems implement a "quiet period" which prevents builds when there have been commits to that configuration in the previous few minutes. Again, commit detection is important.

Subtleties

A related and potentially separate use case is 'detect changes' which merely reports if there are any changes to a workspace. This could be a faster operation used to determine if a build is needed.

Examples

• Bitkeeper – "changes"
• ClearCase – "lshistory"
• CVS – "hist" or "log"
• Perforce – "changes"
• Subversion - "log" or "status -u"

Apply a label

Tag the working set with a string.

Justification

The traditional use of this is to create baselines. Many build servers track build numbers of versions of builds and optionally apply that number to the to the working set after some transformation.

Subtleties

This feature can also be used for non-baseline labels like ‘built_successfully’ and perhaps promotions.

In ALF, this use case would probably be split out into Baseline and Apply Label use cases, but for the majority of build tools, the same abstraction is used.

Examples

• Bitkeeper – "tag" followed by "push"
• ClearCase (base) – "mklbtype" followed by "mklabel"
• Clearcase (ucm) – "mkbl" followed by "chstream"
• CVS – "tag"
• Perforce – "tag"
• Subversion - "copy"
• Version Manager - "pcli label"

5) Prepare file for edit

Perform any steps needed prior to editing a file.

Justification

This is not a core build management server requirement. That said, many build managers like to track the version of the project in a file. This allows for natural pairing of version and configuration that implicitly manages different version numbers on different branches. In order to increment that version, the build management server needs to be able to edit, and check-in the version file.

Examples

• Bitkeeper – "edit"
• ClearCase – "checkout"
• CVS – no operation needed
• Perforce – "edit"
• Subversion - "lock" (optional)
• Version Manager - "pcli lock"

6) Commit a new version

Send changes to a file back to the repository as a new version. on these files releasing any locks on that file.

Justification

See Prepare file for edit.

Examples

• Bitkeeper – "ci" followed by "commit" followed by "push"
• ClearCase – "checkin"
• CVS – "commit"
• Perforce – "submit"
• Subversion - "commit"

7) Produce Difference Report

[proposed for discussion] Produce a report of the differences between two different builds (or labels, or baselines, or tags).

Justification

The build system may want to publish the source code differences that occurred between the last build and the current build.

8) Produce Bill-of-materials Report

[proposed for discussion] Produce a report which may be viewed independent of (and outside of) the versioning tool, for example HTML, which lists all inputs (repository source location, date, time, meta-data tag, baseline, etc.). Advanced: This bill-of-materials could be provided as input to the versioning tool at a much later time, to retrieve the original build inputs. (This may imply, for example, that a reference to a baseline or tag is embedded, that would be a versioning tool domain specific item).

9) Remove a workspace

[proposed for discussion] Remove a workspace. Workspaces can be large and a drain on system resources. Deleting them after a build can save resources.