Branching: branches versus streams

In the course of a collaborative development project, you may find it useful to split off the codeline into multiple codelines, each having a distinct intended purpose. For example, when a certain milestone is reached in development, you may choose to copy the code—also known as branching it—into a new codeline for testing, thereby creating a QA branch. After it passes all tests, it is copied up to the Beta test line where it is subjected to real-world use. Later, you may choose to merge one or more of these new branches back into the main codeline.

Streams: branches with additional intelligence

Streams are like branches, but with additional intelligence built in.

Streams:

  • provide clues of where and how to do branching and merging
  • guide merging and branching actions that support stability and innovation
  • are ideal for implementing the mainline branching model, in which less stable streams merge changes to keep up to date with their parents, then copy work to the parent when the work is stable enough to promote.
  • eliminate much of the work needed to define branches, create workspaces, and manage merges
  • enable the system to generate views for associated workspaces, eliminating the need for you to update views manually to reflect changes to your stream structure.

When you create a stream, you specify its type, information about the files it is associated with, its relationship to other streams, and how files are to be treated for branching and merging. The system uses the information you provide to encourage merging best practices and to track parallel development.

The stream type tells the system how stable the stream is relative to other streams.

The stream’s path information tells the system:

  • which files to populate the workspace with
  • which files child streams are allowed to branch
  • which changelist to lock the files at.

Parent labeling specifies how the stream relates to other streams in the system, helping to determine how change flows through the system.

Note

This guide assumes the reader is using streams, but notes where instructions differ for branch users.