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 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.
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.
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:
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.
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
|
Running (animated)
Success
Warning
FailedIn 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 on page 109 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:
|
The status of at least one of the gated stream’s staging streams is Running. The Running status takes precedence over all others.
|
|
|
The status of at least one of the gated stream’s staging streams is Warning, and none is Failed or Running.
|
|
FailedYou 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.
