Promote: Sharing Your Work

The Promote command sends one or more versions from one stream to another, making the versions accessible in the destination stream — and in workspaces and streams below it. A single transaction in the AccuRev depot records the creation of the new version(s) in the destination stream.

In this topic:

Promote Overview

The basic use of Promote is to take the private versions that you've created in your workspace stream and make them public by sending them to the workspace's backing stream.

Promote can also send versions from a dynamic stream to any other dynamic stream. You can do such higher-level promotion using the File Browser or StreamBrowser. Promoting from a stream to a non-parent ("cross-promotion") can be as simple as drag & dropping the version(s) to the destination stream. However, if there are any conflicts that must be resolved, AccuRev automatically displays the Change Palette.

Back to top

Promoting New Work

Generally speaking, you use promote to share changes to elements that are already under AccuRev control. Note, however, that you can use the promote operation on external files — when you promote a file with an (external) status, AccuRev automatically performs the actions required to place the file under AccuRev control.

Similarly, you can directly promote elements you have modified — AccuRev will automatically save your changes to the depot before promoting.

Back to top

Real Versions and Virtual Versions

The Promote command creates a virtual version in a dynamic stream. No data is copied from your machine to the repository by this command; it just creates new entries in the repository database. By contrast, the Keep command (as well as Anchor, Send to Workspace, Revert, Rename, Defunct, and the CLI-only command undefunct) creates a real version in a workspace stream. See Real Versions and Virtual Versions.

Back to top

Inheritance of Promoted Versions

After you promote a version, it can be inherited by all dynamic streams and workspaces below the backing stream. Inheritance by dynamic streams is automatic; inheritance by a workspace occurs when the user Update's it.

Back to top

Overlap Status and Merging

If an element has (overlap) status, you cannot promote it. You must merge your version with the version in the backing stream, to create a new, merged version. You can then promote the merged version. See Merging Your Changes with Someone Else's Changes for more information.

Back to top

Underlap Status

The status (underlap) is similar to (overlap), in that an element has changed in your workspace and also in the backing stream. With (underlap), the changes in your workspace version have already been promoted to the backing stream (from another workspace, or from a stream elsewhere in the depot’s stream hierarchy). In many cases, it is most appropriate to use the Revert to Basis command to 'undo' the changes in your workspace. In other cases, you can merge and promote, as with (overlap)-status elements.

Invoking the Promote Command

To promote one or more files:

1. In the workspace File Browser, select one or more files from the Details pane.

   Tip: Although you can promote files from the Explorer, Outgoing Changes, and Conflicts modes, consider using the Outgoing Changes mode to see all the new work and changes you might want to promote to the parent stream.

2. Click the button in the Details pane toolbar, or right-click and choose Promote from the context menu.

   What happens next depends on whether or not AccuRev is integrated with an issue-tracking system (ITS), such as AccuWork or a third-party system. If AccuRev is integrated with an ITS, the Select Issue (Change Package) dialog box appears. Choose the issues against which you want to promote your changes and click Ok to continue. See Promoting Changes When AccuRev is Integrated with an ITS for more information. If AccuRev is not integrated with an ITS, the Promote dialog appears.

   

3. Optionally, enter a comment describing the changes you are promoting. (AccuRev "seeds" the text box with the most recent Promote comment made during your current AccuRev GUI session.) The comment string becomes a permanent annotation to the transaction that creates the new version(s) in the destination stream.

   Tip: AccuRev itself does not require a comment, but your organization can establish such a requirement by putting a trigger on the Promote command.

4. Optionally, clear the Promote checkbox for any versions that you do not want to promote.

5. Click the Promote button.

   The elements’ status changes to (backed). If you performed the promote operation from in Outgoing Changes mode, the element is removed from the Details pane.

Back to top

Promoting Changes When AccuRev is Integrated with an ITS

If you are using AccuWork, or if you have integrated AccuRev with a third-party issue tracking system (ITS), when you promote AccuRev executes the default AccuWork query and displays its results in the Select Issue (Change Package) dialog box. You use this dialog box to select one or more issues with which you want to associate the changes you are promoting:

You can select one or more of the issue records and click Ok; or you can type one or more numbers (SPACE-separated) in the Issue input field. When you promote, the integration(s) record information about the Promote transaction in the issue record(s) you designate.

Back to top

Promoting Dependent Elements

A dependent element is an element that has a relationship with another element. Dependent elements must be promoted as a group in order to resolve the dependency. This section describes how dependencies can be created and how to promote them.

How Dependencies Can Be Created

A dependency can be created when you rename an element in the workspace using the name of another element that has also been renamed and promoted to the backing stream. For example, imagine that you add the following files to your workspace, and then keep them and promote them to the backing stream:

proposed_tracker.c
beta_tracker.c
ref_tracker.c

Next you rename these elements in the workspace as follows:

proposed_tracker.c is renamed as accepted_tracker.c

beta_tracker.c is renamed as proposed_tracker.c

ref_tracker.c is renamed as beta_tracker.c

The element accepted_tracker.c can be promoted freely — it has simply been renamed using a new name (that is, the name of an element that has not already been promoted to the backing stream). Notice, however, that elements beta_tracker.c and ref_tracker.c were renamed with names of elements that have already been promoted to the backing stream and now have dependencies (proposed_tracker.c and proposed_tracker.c, respectively), creating a dependency — proposed_tracker.c cannot be promoted from the workspace without accepted_tracker.c. Similarly, beta_tracker.c requires that both proposed_tracker.c and accepted_tracker.c be promoted with it.

Element dependencies can also be created during the twin resolution process.

How to Promote Dependent Elements

When AccuRev detects a dependency during a promote operation, it displays a message alerting you to the dependency and the requirement to promote dependent elements together, as a group.

When you dismiss the message, the Promote dialog box appears. Dependent elements are included in the table, along with any other files you have selected for promote, as shown in the following illustration:

Dependent elements are displayed with a warning icon in the Dependency column. Elements that share a dependency are highlighted using the same color. Because dependent elements must be promoted together, clearing the Promote check box for one element in a group clears the check box for all elements in that group.

Back to top