Promote: Making Your Private Changes Public

At some point, after you have used Keep to create one or more new, private versions of a file in your workspace, you typically want to share the changes you have made with the other team members. To make your (most recent) new version available to the public, you promote it.

The following figure shows how to run the Promote command from the File Browser toolbar. Promote is also available from the Actions and context (right-click) menus.

Promoting your new version of a file does not automatically push it into the workspaces of the other team members. When a user decides that she is ready to incorporate versions of files that other team members have promoted, she pulls them into her workspace with the Update command. This process is described in Update: Incorporating Others’ Changes into Your Workspace.

Streams

The Promote command sends data to, and the Update command gets data from, an AccuRev data structure called a stream.

The stream (named talon_dev in this illustration) acts as a central data exchange for the set of workspaces used by a development team. A stream also has a bit of "traffic controller" built in, preventing team members’ efforts from colliding and providing other mechanisms to control the flow of data.

A stream is not, as you might initially suppose, a set of copies of promoted files. Rather, it is more like a list of version-IDs.

• The 4th version created in workspace talon_dvt_akp of file logic.xml.
• The 7th version created in workspace talon_dvt_mary of file matrix.ini
• Etc...

In SCM vernacular, a stream is a configuration of a collection of version-controlled files. The term stream is apt, because it implies the ongoing changes happening in a development project. Each time a user promotes a version of file logic.xml, the stream configuration changes for that file, for example, from the 5th version created in workspace talon_dvt_derek to the 7th version created in workspace talon_dvt_mary.

Promotion and Parallel Development

Sometimes, AccuRev does not allow you to promote a file to the development team’s stream, because another team member has already promoted the same file (after modifying it in their own workspace). AccuRev prevents you from overwriting your colleague’s change to the team’s shared stream. This situation is called an overlap: two users working at the same time on the same goal, to create the stream’s next version of a particular file.

Before you can promote your changes to the stream, you must first perform a merge on the file that has an overlap. This command is described in Merge: When Changes Would Collide.

Active and Inactive Files

As you work with a file using the commands described above, AccuRev considers the file to alternate between being active in your workspace and inactive:

• The file is initially inactive.
• When you create a new version in your workspace, using Keep, Rename, Move, or Defunct, the file becomes active.
• When you make your private version public, using the Promote command, the file becomes inactive again.

Later, you might restart this cycle, making the file active again by creating another new version of it. Alternatively, updating your workspace might overwrite your inactive file with a newer version that another team member promoted.

AccuRev keeps track of the set of active files in your workspace. Officially, this set is called the default group. You might find it easier to think of it as the workspace’s "active group".

More About Promote

The Promote command does not copy the promoted version to the AccuRev repository. It does not need to. Promotion just gives an additional name to a version that already exists in the repository, having been placed there by a previous Keep command (or Rename, Move, or Defunct). For example, promoting the 7th version created in workspace talon_dvt_mary might give that version the additional name the 3rd version promoted to stream talon_dvt.

Just to emphasize the previous point: a stream does not reside in the file system, but in the database used by the AccuRev Server. Promoting a version to a stream does not create a copy of a file, it just creates an additional file-reference in the database.

It might seem strange at first that deleting a file with the Defunct command makes the file active. The File Browser continues to list the file, with a defunct status, even though the file has been removed from your workspace’s disk storage. This design feature enables AccuRev to implement the file-deletion operation using the same private-change/public-change scheme as all other changes.

We have discussed the stream that is the basis for a set of workspaces. But a typical development project has many streams, organized into a hierarchy. Promoting a version to a higher-level stream from a lower level stream makes that version "even more public", for example, available to users outside your local development team.