A gated stream is a stream that you use to control whether changes promoted into it are automatically promoted out of it, often based on meeting externally established criteria (such as passing a test suite or completing a successful nightly build). Gated streams combine attributes of both dynamic and pass-through streams, and they have features that are unique to them. For example, like dynamic streams, the content of a gated stream changes over time; and like pass-through streams, versions promoted to a gated stream pass through it to the gated stream’s parent. Unique to gated streams is a special type of stream called a staging stream. Staging streams are described in the following section.
The following illustration shows a gated stream, nightly_build, which has been created off the integration dynamic stream:
You create gated streams explicitly, as you would any other stream in AccuRev -- simply choose Gated stream in the New Stream dialog box in the AccuRev desktop GUI, or use the --gated option for the mkstream command in the AccuRev command line interface (CLI). (You cannot create gated streams using the AccuRev Web UI.) See Creating Gated Streams for more information.
A staging stream is a child of a gated stream that AccuRev creates automatically when you create or reparent a stream or workspace off the gated stream. You cannot create staging streams explicitly (nor can you reparent them). The following illustration shows a staging stream, nightly_build_staging_1, which was created off the nightly_build gated stream when the workspace integration_hchance was reparented to the gated stream.
Default staging stream names are based on the name of the gated stream, with a suffix of _staging_n, where n is a number. Consider the preceding illustration: if another workspace is created or reparented off the nightly_build gated stream, the new staging stream associated with that workspace will be nightly_build_staging_4. If you choose to rename a staging stream, the general rules about stream names apply (they must be unique across the repository, they can begin with a digit (provided there is at least one non-digit in the name), and so on).
|
•
|
You choose Show All Staging Streams from the gated stream’s right-click menu. This command causes the StreamBrowser to display all of the gated stream’s staging streams, regardless of whether or not they have a default group. (This is shown in the preceding illustration.)
|
Tip: Do not be concerned if you see staging streams "disappear" from the StreamBrowser. Once changes are promoted out of the staging stream and it no longer has a default group, AccuRev removes the staging stream from the StreamBrowser to avoid visual clutter. You can display them, if desired, using the Show All Staging Streams command.
The previous sections described gated and staging streams, how they are related, and how they behave. But it is the server_master_trig trigger -- and more precisely, the customizations you define for it -- that determines what AccuRev does with changes that are promoted into a gated stream.
The server_master_trig trigger is a repository-wide trigger that runs after certain AccuRev commands are executed. In the case of a gated streams implementation, this trigger runs after changes are promoted to the staging stream. Because it is repository-wide, the server_master_trig trigger affects all depots you have created on the AccuRev server.
Triggers are written in the Perl programming language, and while you can write triggers to do whatever you like, the sample server_master_trig trigger installed with AccuRev provides a commented template to help you customize it based on your needs. Among other things, you can customize the server_master_trig trigger to:
|
•
|
Provide links to logs and other resources for troubleshooting problems with external tools
(http://example.com/test_suites, for example) |
|
•
|
Display tooltips that describe the current status (Test suite 2 passed, for example)
|
|
•
|
Call other triggers -- like email_post_promote, which can be configured to send email to members of your team to alert them of changes requiring their attention
|
See Implementing the server_master_trig Trigger for more information.