Working-Sets

This feature is available since Dorothy (21.04), as experimental feature. Available as supported feature from Emma (21.09).

Introduction

The definition of a complex product contains dozens of components. A component usually consists of dozens of specifications like Requirements Specifications, Test Specifications, Design Specification and others managed in multiple codebeamer trackers. For each of the trackers, the right version or variant has to be selected to result in a consistent component. Usually, users will work in the context of a specific component and are interested only in specification versions relevant in that context. Considering the number of specifications involved in a complex project the user will not be able to work efficiently if he additionally has to consider different versions and variants of specifications.

Working-Sets are supposed to fill that gap by enabling the grouping of different specification versions and providing a context to work in to the user.

The main concepts of Working-Sets are:

• Working-Set: Working-Sets are defined in a specific project and do include trackers at a defined version (head, baseline or branch) for each selected tracker. By combining different versions of trackers it is possible to define a Working-Set.
• Included tracker: A copy of a tracker that was branched from the original tracker at a point in time. After creating the Working-Set two copies of the tracker exist and these copies can be modified independently of each other.
• Shared tracker: The selected tracker is included in the Working-Set, but not branched. After creating the Working-Set the tracker is shared between the original Working-Set and the new one. The tracker can be modified, but it is visible in both Working-Sets. A tracker can be shared in multiple Working-Sets.
• Excluded tracker: Tracker is excluded when it is not part of the Working-Set. External trackers are available in the context of the Working-Set.
• Default Working-Set: In every project, there is a predefined “Default” Working-Set that does contain the “Master” branch of all Trackers in the project.
• Merge: The process in which the changes from one branch are applied to its original one. During the merge process, the user has the ability to select which changes he wants to copy to the target branch. After the merge, the branches can still be modified independently from each other.
• Working-Set hierarchy: Working-Sets can also be derived from existing Working-Sets. This is the same process as creating a Working-Set from a Default Working-Set (Master branch) but instead of including, sharing, or excluding trackers from the Default Working-Set, they are originated from the selected Working-Set.
• Non-brancheable trackers: these trackers cannot be included in a Working-Set, only shared or excluded. Non-brancheable trackers are test run, release, team, platform, test configuration, work log, issue, contact, bug, and document.

See Working-Set Use Cases for more information on high-level Use Cases supported by Working-Sets.

License and Permissions

Branching license is required to be able to use the Working-Set feature.

Your license must include the Working-Set option to access the Working-Set feature. Codebeamer defines two Working-Set related project permissions:

• Working-Set - View: Allows users to view Working-Sets.
• Working-Set - Admin: Allows users to administer Working-Sets. Users with this permission can create and merge Working-Sets.

Users with Working-Set Admin permission are able to configure the trackers in the Working-Sets they created.

Creating Working-Sets

How to Create Working-Sets

You can create a Working-Set from two places (but only if you have the Working-Set - Admin project permission).

• Click on the three dots of the Admin tab and select Create Working-Set

• Go Trackers page and click the Working-Set icon

This will show you a popup editor dialog like this:

The fields of this form:

• Name: this is the name of the Working-Set. Mandatory field.
• Color: an optional color. It will be used as the header color to make it more recognizable.
• Key postfix: optional postfix. By default it is empty. Will be used in the interwiki links of Working-Set items.
• Description: an optional description for the Working-Set.

When all set click on Next (Select Trackers) to navigate to Trackers Selections Window:

Selecting trackers:

• Trackers are grouped into Work Items and Configuration items
• By default all available trackers are selected:
  • Non-brancheables are selected as shared trackers
  • Other trackers are selected as included trackers
• If the project has at least one baseline then baseline selection combo-boxes are available:
  • One on the top to set the common baseline for the whole Working-Set
  • Each included tracker has one to set a tracker specific baseline.
  • By default 'HEAD' is selected for all.

Click 'Next (Done)' to navigate to the summarize page:

Working-Set creation runs in the background. This means that the created Working-Set is not available immediately. User will receive a notification email and a pop up message will be shown in the browser:

Validation

Before creating or extending the Working-Set codebeamer will validate that:

• The name of the Working-Set is unique.
• The total number of items in the included trackers is less than a given number (default 10000)

Background job

Both Working-Set creation and extensions run in the background. The Working-Set is unavailable until the job is done. When the job is finished a notification email and a pop-up notifies the user.

By default Working-Set jobs run sequentially, one after another.

In case of a server restart, the background job can recover from an inconsistent state. Before running the job it checks if it was running before and if so, it cleans up the inconsistent state and starts the process from the beginning.

Baseline creation

During Working-Set creation/extension two type of baselines are used:

• A temporary one, which is created when the user requests the job. It ensures that even if a long job is in the queue the Working-Set will be created from the requested 'state'.
• A permanent one, which is created right after the Working-Set creation is done. The baseline name is the same as the name of the Working-Set. When renaming the Working-Set it also triggers baseline renaming.

Migrating Existing Branches / Orphan branches

In previous versions of codebeamer, it was possible to create branches without Working-Sets.

As of now, branches can be built by creating a Working-Set only which must be associated with another Working-Set to be accessible for the users. To continue working with existing branches, assign them to an existing or a new Working-Set.

E.g. If there is an orphan branch of a Tracker (e.g.: Tasks) the does not belong to any Working-Sets, it can be chosen if the parent Tracker is selected.

In this case, the already existing branch is used and behaves as an included Tracker, therefore, no new branches will be created for that.

If there are more than one orphan branches belonging to a Tracker, only one of them can be chosen to be included.

Reference Rewriting

During creation of a Working-Set references to items and the corresponding configurations will be rewritten according to following rules. Despite the fact you can configure references outside of working-sets, currently you can select reference items only within the current working-set.

Included Trackers

1. Included tracker (Task) references an included tracker (User Story):
   • Both trackers are branched and reference is added between them.
   • 
2. Included tracker (Task) references a shared tracker (User Story):
   • Included tracker is branched and it references the shared tracker(User Story)
   • 
3. Included tracker (Task) references an excluded tracker (User Story):
   • Included tracker is branched, but the reference is not added
   • 

Shared Trackers

1. Shared tracker (Task) references an included tracker (User Story):
   • Included tracker branched and a new reference added to it.
   • 
2. Shared tracker (Task) references a shared tracker (User Story):
   • Nothing changes
3. Shared tracker (Task) references an excluded tracker (User Story):
   • Nothing changes

Excluded Trackers

1. Excluded tracker (Task) references an included tracker (User Story).
   • Included tracker is branched, but the reference is not added
   • 
2. Excluded tracker (Task) references a shared tracker (User Story).
   • Nothing changes
3. Excluded tracker (Task) references an excluded tracker (User Story).
   • Nothing changes

Using Working-Sets

Navigating between Working-Sets

You can navigate between Working-Set using the combo-box in the header of the codebeamer user interface.

Selecting a Working-Set will open the same page in the requested Working-Set. The header will use the color configured for the Working-Set to simplify distinguishing different Working-Sets.

When switching between Working-Sets, a warning pop up message is shown like the one below:

You can also change Working-Set in an item details view if and only if the item being viewed has a corresponding version in the Working-Set to be switched to. In this case the item shown will also be switched to the version of the target Working-Set.

Baselines

Screens that do include the Working-Set selector show the selected baseline as part of the selected Working-Set.

The actions for the baseline such as leaving the baseline or opening the "Baselines and Branches" dialog can be reached by opening the Working-Set selector.

Badges

Trackers that are not branched in the Working-Set but shared with the Default Working-Set or the parent Working-Set are marked with the Shared badge.

References that are pointing to items that are not part of the current Working-Set are highlighted with a yellow background. Following such references will usually lead to switching to the Working-Set containing the target item.

Most views listing item, for example table view use a badge to indicate the Working-Set that does contain the item right next to the name.

Modifying Working-Sets

Editing Working-Set Properties

Select the Working-Set to be edited using the combo-box and hit the icon next to the combo-box:

Select 'Edit''' to edit Working-Set properties:

Update Working-Set dialog:

The fields of this form:

• Name: this is the name of the Working-Set. Mandatory field.
• Color: an optional color. It will be used as the header color to make it more recognizable.
• Key postfix: optional postfix. By default it is empty.
• Description: an optional description for the Working-Set.

Click 'Save' to save changes or 'Cancel' to close the dialog without saving.

Adding new Trackers to Working-Sets

Newly created or previously excluded trackers can be added to existing Working-Sets. Generally all trackers have to be created in the "Default Working-Set", the option to create trackers in any other Working-Sets is disabled.

Select the Working-Set to be extended using the combo-box and hit the icon next to the combo-box:

Select 'Add Trackers''':

'Add Trackers' dialog:

Modifying already added trackers:

• It is not possible to remove a tracker that is already added.

Adding new trackers:

• Non-brancheable trackers can be only added as shared trackers.
• Brancheable trackers can be added as shared and included too.
• Baseline:
  • No 'common' baseline is available.
  • Non-brancheable trackers use the 'HEAD' version.
  • Included trackers set to 'HEAD' version by default but can be modified to the required baseline.

Click 'Next (Done)' to navigate to summarize page:

Select 'Update Working-Set' to save modifications or 'Previous' to return to the previous page.

Deleting Working-Sets

Select the Working-Set to be deleted using the combo-box and click the gear icon next to the combo-box:

Select 'Delete':

Confirm delete by 'Yes, delete' or select 'Cancel' to return:

Copying Configurations into Working-Sets

Since Codebeamer release HUSKY, the configurations of any parent working-set can be copied into the derived working-sets. It is highly recommended to edit the configurations of the default working-set and copy it to all the relevant derived working-sets.

To copy the configurations into working-sets,

1. On the top right next to the Working-Set selector of Trackers tab, click the Gear icon > Copy Configuration option.
2. In the Copy Working-Set Configuration window, select the working-sets which the configuration of the parent working-set needs to be copied into.
3. Click Copy to execute.

When performing a configuration copy, all the settings on the Permissions, State Transitions and Fields tabs are copied into the selected working-sets.

The Copy Configuration function can be applied within the whole working-set hierarchy.

If a working-set has only one child working-set, by selecting the child working-set to copy a configuration into, its parent working-set gets automatically selected to ensure consistency. In case more children working-sets are available within a parent working-set, the user can select which child or children working-sets should the configuration be copied into.

Clearing the selection of a parent working-set removes the selection of the child or children working-sets as well.

Once the relevant working-sets are selected and the user clicks Copy, a background job performs the configuration copy.

Since working-set external references are not allowed in working-sets, the field configurations and values of the reference fields are updated accordingly after the configuration copy is executed.

For example, a reference field in the default working-set collects the references from the default User Story. After copying its configuration into, for instance, Working-Set 1.2, its reference field gathers references from the Working-Set 1.2 User Story.

Reviewing and Merging Changes

Working-Sets can be used to work on different versions or variants of specifications in parallel without interference. When working on the same specification in different Working-Sets in parallel it is essential to efficiently identify and merge changes implemented on the different Working-Sets.

Modifications in Working-Sets

Initially (after creating the Working-Set) the items on the Working-Set are the exact copies of the original items. Whenever you update or create an item either on the Working-Set or the parent you will get notification badges on the document view. An example:

The possible badges are:

• Created on Working-Set: the item was created on this Working-Set after the last merge, it does not exist on the parent Working-Set
• Updated on Working-Set: the item was updated on this Working-Set after the last merge and it is actually different from its pair on the parent Working-Set
• Updated on Default Working-Set: the pair of this item on the Default Working-Set was updated after the last merge and is actually different from the Working-Set item

Clicking on the Updated badge will show the actual differences in a dialog, and you can use this dialog to merge the items one by one:

These badges are cleared after merging between the Working-Set and its parent.

Merging Working-Set Trackers

In some cases, it is useful to get the changes from a Working-Set tracker to another tracker. An example: the quality team finds a bug in a variant and verifies that the same bug exists in other variants too. Instead of fixing the bug in each variant, it might be useful to fix it in only one of them and apply the fix to the other variants. This is one case when merging is useful.

Every tracker included in a Working-Set (i.e. not shared) is associated with a branch of that tracker in the background.

The merging process consists of the following steps:

• Selecting the branch to merge. This means selecting the source branch (in the example above this is the branch where the bug was fixed) and the target branch.
• Selecting the changes to apply to the target branch.
• Executing the merge

Selecting a branch to merge

In codebeamer, you can merge between any parent-child branches. You have two options for starting a merge:

• in the more menu of the branches there are two relevant menu options: Merge to Default Working-Set (or parent) and Merge from Default Working-Set (or parent). The first option will use the current branch as the source and the parent branch as the target, while the second option will use the parent branch as the source and the current branch as the target.
• if you click on an 'Updated on Working-Set' or 'Updated on Default Working-Set' badge it will open a merge dialog with only one item selected

Alternative way to merge branches

You can also start a merge through the "Baselines and Branches" dialog, which can be opened using the button in the action bar of a tracker page.

You can see the above page when selecting the "Branches" tab. Here you can see all the branches (even those not associated with a Working-Set) of the current tracker. You can select two branches for merging (any two can be selected independently from the current branch, but the current is selected by default). If one branch is selected, the other branch must be an ancestor or a descendant branch (the other ones will be disabled). The merging can be started by clicking the "Merge branches" link.

Executing the merge

On the merge dialog, you can see all the differences between the selected branches.

The dialog shows the different field values and the badges.

To see and merge relevant changes only, choose from the following Filters:

Report: Select a single report to reduce the displayed merge items. Use this filter carefully because it is possible that the selected report might not contain items from one of the branches. Only those changes are merged that are currently visible.

Apply to side: If you selected a report, the filter is locked to the right (Source) if Created is selected under Difference type. Similarly, the filter is locked to the left (Target) if Deleted is selected under Difference type.

Difference type: Select from All, Updated, Created, or Deleted, to filter based on the displayed items. If Updated or All are selected, the Apply to side filter is not restricted to either side.

Field: Select from the available fields to filter the displayed items. This filter applies only to Updated items. The filter is enabled only when All or Updated are selected under Difference type. The filter is not enabled when the Created or Deleted are selected Difference type. By default, All fields are selected except the ones marked as Omit Merge. This means that by default, items with changes only in omitted fields are not shown.

After you have made your filter selection, click GO.

Mark all as merged: If you select this check box, badges will be removed from all matching items, not only the ones that are shown on the current page. If you select a report and select this check box, only those items are merged that match the selected report and the filter combination. If you select a different report, any earlier check box selection is cleared.

Copy all created: If you select this check box, all items created on the branch and visible only on the current page, will be copied to the target.

For items that were created on the Working-Set you have only one checkbox. Checking it will copy the item to the target branch and create a hidden reference between the copy and branch item. From this point you can track the field changes between the items.

For updated items you can select which fields to copy to the target item by clicking the apply button for the field. If you want to copy all field values of an item then just click on the Apply button in the row of the name. This will apply all changes.

You also have a Mark as merged option for each updated tracker item. This is useful in the cases when you don't want to merge any field changes between the branches but want to acknowledge that the change is not important for you. Clicking this option will clear the badge on the document view without actually merging the changes.

The Swap Branches option changes the direction of the merge. So what is now the source branch will become the target and the target branch will become the source branch. If you click Swap Branches, your filters are retained.

Click Apply All for a bulk update on the current page, or click Apply to merge specific changes.

When you are ready with selecting the changes to apply click the Merge button for the items on the current page. This will apply the selected changes and redirect to the source Working-Set branch. After the selected changes are applied the badges of the merged items are cleared.

If there are items on subsequent pages, repeat the steps for the merge operation, to merge the items on subsequent pages.

To adjust the page size, see: Application Configuration.

Updating Downstream References during a Merge

When working on Working-Sets you might add new downstream references to some items. In some cases it makes sense to update these references during a merge so that they also reference the master or parent item. For example you find a bug related to a user story on one of your branches. You fix the user story and decide to merge the fixes to the Master branch. Since the bug is also present in the Master version you would like to update the bug during the merge as well.

To make this process easy we added a New Downstream References section to the diff page:

This section shows all the Downstream references of an item that point to the branched version but not to the Master/parent item. You can select some of the checkboxes to update those references. You can also update these references without selecting any other changes of the branch item.

There are some restrictions:

• if you have no permission to update the referring item or the specific field of the referring item then you won't be able to select the reference
• this feature only works when merging to the parent branch
• the added reference will always point to the HEAD version of the item on the parent branch

Skipping fields during merge

There are some fields that might change frequently but are not as important so that you want to merge them every time. For such fields you can check the Omit merge option on the field configuration page.

If this option is checked then the fields are shown in a separate group. Of course you can open this group and click the apply button for them as well.