Example: A Simple Use Case

Now that you have been introduced to all of the components that are part of the AccuRev gated streams feature set -- gated streams, staging streams, and the server_admin_trig trigger -- let’s walk through a simple use case to see how these components work together to help ensure that changes are promoted and shared with others only when ready.

The barcon Depot

The barcon depot uses a stream hierarchy that might look familiar to many software development organizations. It contains a product release stream, barcon; a QA stream for testing; and a build stream, integration. Individual developers dfoster, oarmstrong, and hchance have workspaces off the integration stream.

In this stream structure, the developers promote their changes to the integration stream. A build is run when changes are promoted, as well as on a nightly schedule; if the build succeeds, the developer promotes the changes to the QA stream for testing. Other developers on the team are free to update their workspaces as soon as changes are promoted to integration.

Identifying the Need for Gated Streams

Occasionally, changes promoted by a developer break the build. This not only slows down the development process, but it creates additional problems for the other developers on the team who have updated their workspaces with these changes. While there are ways to address such problems after the fact -- using demote, for example -- the administrator decides to create a gated stream between the workspaces and the integration stream, and to use the server_master_trig trigger to ensure that code that breaks the build cannot be promoted.

Once the administrator creates the gated stream nightly_build, the developers reparent their workspaces to it, as shown in the preceding illustration. Under the covers, AccuRev creates a staging stream for each of the reparented workspaces, like those shown here:

Recall that AccuRev does not display staging streams by default -- they appear only if they include active elements, or, as is the case here, if you explicitly elect to display them using the Show All Staging Streams choice on the gated stream’s right-click menu.

Setting Up the Trigger

Once the gated stream has been created and the necessary workspaces have been reparented to it, the final step to implementing gated streams is to set up the server_master_trig trigger. By default, the sample server_master_trig trigger installed with AccuRev:

•	Locks the staging stream while the trigger is executing

•	Displays a status icon that indicates the status of the changes (or, if needed, problems encountered executing the trigger)

•	Displays a tooltip for that icon

As mentioned previously, you can write Perl to make an AccuRev trigger do anything you want. For the barcon depot, the server_master_trig trigger has been customized to start a build when changes are promoted, and it includes code that updates the status of the staging stream based on the build’s results.

Promoting Changes

Now when changes are promoted into the nightly_build stream, AccuRev:

•	Displays the staging stream for the changes (nightly_build_staging_1, for example)

•	Executes the server_master_trig trigger

•	Displays the status -- of either the trigger execution or the external job, as summarized in the following table

While a trigger is running, you might see one of the following status icons on the staging stream associated with the workspace from which the changes were promoted:

Icon		Description
Running (animated)		The job associated with the promoted changes is running.
Success		The job associated with the promoted changes completed successfully.
Warning		The job associated with the promoted changes completed with warnings.
Failed		The job associated with the promoted changes completed with failures.

In this example, the changes promoted to nightly_build broke the build, as indicated by both the status icon and tooltip displayed on the nightly_build_staging_1 staging stream:

At this point, the user hchance needs to fix his code before he promotes it back to the nightly_build_staging_1 staging stream. Once he does, the trigger re-executes and the build is run again. This time, assuming the fixes are valid and the build succeeds, the changes are promoted from the staging stream, through the gated stream, where they become part of the integration stream’s default group and will be available to the others when they update their workspaces.

Tip: Note that the gated stream displays a status icon that reflects the status of its staging streams, even when those streams are not displayed. See Understanding Gated Stream Status for more information.

Once the staging stream is empty -- that is, once all of the active elements in its default group have been successfully promoted -- AccuRev removes it from the StreamBrowser. (AccuRev hides staging streams by default if they don’t have any active changes.) You can use the Show All Staging Streams choice on the gated stream’s shortcut menu to display empty staging streams, as shown in the following illustration:

Understanding Gated Stream Status

AccuRev displays a status icon on gated streams that represents a summary of the status of all of its staging streams. The same status icons are used for both gated and staging streams, but they have a slightly different meaning when displaying summary status information on gated streams, as described in the following table:

Icon	Description
Running (animated)	The status of at least one of the gated stream’s staging streams is Running. The Running status takes precedence over all others.
Failed	The status of at least one of the gated stream’s staging streams is Failed, and none is Running.
Warning	The status of at least one of the gated stream’s staging streams is Warning, and none is Failed or Running.
Success	The status of all of the gated stream’s staging streams is Success.

The "roll-up" status icon on gated streams lets you quickly check on the status of the jobs associated with a gated stream’s staging streams, even if those staging streams are not currently displayed in the StreamBrowser. Note that staging streams that have no active changes in the default group do not contribute to the roll-up status for the gated stream

Adding Gated Streams

You can use multiple gated streams in your stream hierarchy. In the barcon stream hierarchy, for example, the administrator has decided to add a second gated stream, this one in front of the QA stream to ensure that any changes promoted out of the integration stream pass a suite of tests on the Silk Test platform.