Branch Documents

Polarion supports branching of entire Documents or branching of existing Document-based Work Items into a new Document, in both cases creating a variant Document. As an illustrative use case, consider a scenario where there is an existing requirements specification for some application — a game, for example. The original specification is for the game running on desktop computers. Now there is a decision to create variants of the game for several popular mobile platforms and devices.

Much of the original specification is applicable to all the variants — rules of the game, for example. However, the user interactions are different for each mobile platform, so you need some way to specify platform-specific requirements while keeping those that a applicable to all platforms However, the scenario doesn't end there. Some of the user interactions are the same across all devices running Mobile Platform A, but there must be additional requirements for one or more specific supported devices running Platform A.

In this scenario, the requirements specification Document for desktop platforms is branched to create variant specifications for two supported mobile platforms — Platform A and Platform B. In each of the branched variants, some requirements from the master — that is, the original Document — are referenced, which means that they appear in the variant, but are not contained in it, and may not be modified in it. In the Platform B specification, one requirement from the master is removed from the variant and replaced by a new platform-specific requirement. Then, new native Work Items — that is, items created in the branched Documents — are added to the branched specification Documents to address requirements specific to each platform. The native items are of the User Story type because the mobile development uses the Scrum methodology.

At this stage the specification Documents are Desktop Requirements Specification (master Document), Mobile Platform A Requirements Specification, and Mobile Platform B Requirements Specification. If Work Items in the master Document are modified, the changes propagate to the variant Documents. In cases where this is not wanted, or is not wanted until some future time, the variant Documents can be frozen to a specific Revision of the master Document, meaning that subsequent revisions of the master's Work Items do not propagate to variants until such time as the variants are unfrozen, which means the branch is then live, and all subsequent modifications of the master Document's Work Items will propagate to variants.

Now, the device variants on Platform A need to be addressed. The new native requirements from the Platform A specification are valid for Device 1, but there are some additional ones required to support the device. The approach here is to create a new Document, and then copy all applicable content from Mobile Platform A Requirements Specification and paste that content into it. Any headings and plain text are copied verbatim and changes in the Platform A are not propagated. Copied and pasted Work Items are referenced Work Items — they appear in the Device 1 specification Document, but are not contained in it. Referenced Work Items can only be modified in the Document in which they are native — in this case the Platform A specification.

If the project of the original Document(s) is configured to support Document Types and Document Workflow:

  • The Document Type of any branched Document is the same as that of the original Document from which it was branched.

  • The workflow is reset for every branched Document. Its status is set to the initial status specified in the project workflow configuration, and any initial workflow action specified in the workflow configuration runs.

Variants based on a revision

There may be situations when a variant needs to be based on a specific historical revision (not depicted in the previous figure). For example, suppose requirements for Device 2 need to be based on the Platform A specification as it was at the time of Release 4. Assuming the a project Baseline was created at the time of this release, you could open the project Baseline, browse to the Platform A specification, copy content from the baseline Document, and paste into the variant Document (opened in another browser instance). Alternatively, you could open the baseline revision of the Document in History and use the Branch Document feature in the Document Editor.

In the variant Document (Device 1), any of the referenced Work Items can be frozen to a specific revision of the Work Item. If the items are subsequently updated in the source Document (Platform A specification), the changes do not propagate to the branched Work Items in the variant Document until such time as the Work Items in the variant are explicitly unfrozen by a user. Freezing referenced Work Items to a revision would generally not be needed when the source of the items is a historical revision of a Document, because the source Document revision cannot be modified.

Create a branched document

In order to branch a Document, you must have permissions for creating new Documents and new Work Items in the project where the branched Document is to be created. You can branch the current state of the Document, or the state from a Baseline or other historical revision of the Document.

Branch the current state

This section describes how to branch the current state of a Document, which is the Head revision in the repository.

  1. Locate the Document you want to branch and open it for editing.

  2. On the toolbar of the Document Editor, click and choose Branch in the drop-down menu. The Branch Document dialog box opens.

  3. Set the dialog box fields as follows:

    • Title: Optionally specify a new title for the branched Document.

      If you want to branch a revision other then the current one, click the button (labeled HEAD or with the number of the revision you are branching) and select the revision from which to branch a new Document.

    • If you have modified the Title field, and you want the heading styled as Title in the Document updated to that value, select the check box labeled Update Title (Heading) in the Document. Clear the box if you want the original title preserved in the Document's title heading.

    • Name (ID): If you want to create the branched Document in the same space as the Document you are branching, you must enter a new name/ID. The new value must be unique within the space.

    • Project: If you want to create the branched Document in a different project, select the target project in the drop-down list. The default value is the name of the current project.

    • Space: If you want to create the branched Document in a different space than the one selected in this field, select the target space in the drop-down list. The list contains the names of spaced in the project selected in the Project field.

  4. Click OK to create a new branched Document in the specified project and space.

Branch a historical revision

  1. Open the Document to be branched, and click History to open the Document's history.

    A list of historical revisions appears.

    (Document Baselines are blue and Project Baselines are pink.)

  2. Locate the revision you want to branch, and in the Actions column click Show to open the revision.

  3. On the Document Editor toolbar, click and choose Branch.

  4. Set the dialog box fields as described in section Branch the current state.

Branch a Document Baseline

  1. Open the Document to be branched, and click the History icon to open the Document's history.

  2. On the toolbar of the History view, select the Show only baselines option.

    (Document Baselines are blue and Project Baselines are green.)

  3. Locate the Document Baseline you want to branch, and in the Actions column click Show to open the baseline version of the Document in the Document Editor.

  4. On the Document Editor toolbar, click and choose Branch.

  5. Set the dialog box fields as described in section Branch the current state.

Note:

A Document Baseline is essentially a named historical revision of the Document. When you follow the above procedure, the Branch Document dialog box displays the revision number of the Document Baseline on the Revision button rather than the Document Baseline's name.

Branch a Project Baseline

The procedure is similar to that described in the previous section on branching a historical revision.

  1. Open the Project Baseline containing the captured the state of the Document that you want to create a branched Document from.

  2. Click History on the Document Editor toolbar to open the Document's history.

  3. Locate the target Project Baselines that you want to branch.

    Project Baseline revisions have a pink background in the revisions table, and the Revision # column contains the name of the Baseline as well as the revision number.

  4. Click Show in the Actions column of the your target Project Baseline to open the revision.

  5. On the Document Editor toolbar, click , choose Branch, and proceed as described in Branch the current state.

Branch a filtered Document

You might want to create a branched Document that references only a subset of the Work Items in the master. For example, you might create a branched Document containing only items having severity Must Have and status Accepted.

To create such a branched Document, you must first filter the master document so that it shows only the Work Items you want referenced in the branched Document. With the master Document open in the editor, click the and choose Filter. Enter a query that filters the Document's Work Items. For example, status:accepted AND severity:must_have.

When the Document is filtered as you want it, proceed to branch it the same way as an unfiltered Document.