You are viewing the documentation for Blueriq 14. Documentation for other versions is available in our documentation directory.
Table of contents
Introduction
Blueriq version management helps you keep track of and provide control over changes to your models. Version Control Management (VCM) is the management of changes to projects. It ensures that multiple developers can make different changes without interfering with each others work, that there always is a releasable version of the project and that the project can be released, even if not all features have been implemented.
Version management can be found on the Studio home page. User roles may apply to this part, for instance privileges to create or modify branches.
Please refer to the Version management guide in the Blueriq Knowledge Base to learn more about version management.
Concepts
Blueriq projects consist of modules and are part of branches, that form a repository. These concepts are explained in the visual shown below. As mentioned on the main page of this document, the visual does not aim to be complete, but to provide insight.
Repository
A Repository can be viewed upon as a sort of file folder where all your future application development will be stored.
In Version Management you can create, edit or delete a repository. To create a new repository select New repository in the menu ribbon.
A repository has the following characteristics:
| Property | Description |
|---|---|
| Name | Name of the repository, e.g. the functional name of your application |
| Initial branch type | Optional, read about branch types |
| Initial branch | The first branch, e.g. "trunk" |
| Initial register message | Message to register the creation of the repository |
The Name of the newly created repository can be changed later by selecting Edit repository in the menu ribbon.
To delete a complete repository you will no longer need to delete every branch in the repository. Please be carefull while deleting, as we cannot revert this action.
Branch
A branch is a version or duplication of a certain state of your application, for instance to be able to apply modifications to your application in an isolated environment or to isolate it as a release version. When creating a new repository an initial branch has to be created.
A branch has the following characteristics:
| Property | Description |
|---|---|
| Branch type | Optional |
| Name | Name of the branch e.g. name of a feature, release indication |
| Functional name | Optional, can be used in documentation |
| Description | Optional |
You can define your own branch types. This could be helpful for structuring your repository or for applying user roles.
A branch type has the following characteristics:
| Property | Description |
|---|---|
| Name | Name of the branch type e.g. "Development" or "Feature" or "Release" |
| Functional name | Optional, can be used in documentation |
| Description | Optional |
Create a new branch
To create a new branch in Version Management, determine which repository and which branch should be the the basis of the new branch. You can either:
- Copy an entire branch: select a branch and select New branch in the menu ribbon, or select a branch and the top revision in the History of registers and select New branch.
- Create a branch from a certain revision in a branch: select a branch and a certain revision and select New branch in the menu ribbon.
For instance, to create a new branch of trunk containing Change A en X, but not Change B, select the revision Change A in the main screen and select New branch in the menu ribbon.
Continue with providing a name and description of the new (feature) branch and optionally a branch type.
Save this branch and select it on the left side. Click on Open branch on top of the window and you are ready to use the branch.
Other branch functions
Select a branch and choose:
- Open branch - will open the selected branch
- Edit branch - change the properties of the selected branch
- Delete branch - delete the selected branch
- Update from branch - view Merging
- Distribute to branch - view Merging
Registering
By registering changes you keep track of the history of your development. This will enable you to find out when and why a certain change was made, who made the change, or which releases might be affected by a bug.
Each time you register your changes a 'snapshot' is recorded in the version control system. These 'snapshots' are called revisions.
Common practice is to register your changes as soon as you complete building and testing a new feature or bug fix. In order to get a good record of changes each modeler registers his own changes.
There are two locations from where you can register your changes:
- When you are in a project access via File - Pending changes
- When you are on the branch overview, select Branch on the lower left part of your window. Then select Pending changes from the ribbon.
It doesn't matter from which location you open the pending changes window. In both cases all changes made in the branch are displayed. So if you branch contains multiple projects, changes to all projects are listed for registration.
You can select all or a subset of changes in a certain branch to be registered.
Actions
- Registration message: On the top of the screen there is a registration message, this message is required. This message is important because it provides insight in the reason changes were made and what changes were made to your project(s). The message will appear in the history timeline. The registration message cannot be altered once the changes are committed.
- Tags: Next to the registration message are the tags. Tags are used to put a label on a specific revision. For instance a tag 'RC_1' could indicate that this revision is release candidate 1. You can put multiple tags on a revision. Tagging can be done during change registration, but you can change, add or remove tags at any time.
- Revert: Before registering all changes you should check them first whether they are still relevant. It might be possible that some of the changes are incorrect or obsolete and you don't want to process them. You can do this by reverting the changes (by using the right mouse button). This will bring the element in the state of the previous revision. Note that reverting is different from unselecting the change - the latter action will only postpone the registration, but it will be still part of your branch. Be careful, reverting changes cannot be undone.
History of registers
Within Version Management you can select a repository and a branch to view the history of registers. This can also be viewed from within a project.
On the bottom left you see the repositories for which you are authorized. When there are a lot of repositories, the repositories are displayed collapsed. Hover over the repository icon to see its name. To display more repositories:
- drag the line above the repositories up
- or click the arrow next to the collapsed repositories to get a menu that lets you select all collapsed repositories and repositories that are not displayed at all.
Repository content
Once you have selected a repository, the branches in that repository are displayed on the top left of your window. Select a branch to view its revisions in the top right window pane. Select a specific revision to view the changes in that revision in the bottom right pane.
Merging
After registering changes, the changes can be synchronized with the other branch(es) so they are available there. This is called merging. Merging can be done between branches or between a branch and the trunk. Let’s say the project with new feature X has to be released before a specific deadline. The developer now merges his changes with the trunk. Only new feature X was registered so the changes made on feature Y are not copied to the trunk during this merge. Now, the project can be released without delay and the developer can continue working on feature Y. Also, keep in mind that the bug fixing in branch 2 was still in progress during this process without interfering with the development of the new feature or the new release of the software.
There are two options to merge branches. The only difference is the direction of merging: to or from a branch. You can merge either from Version Management or from within a project.
- Update from branch: select the branch you intend to update, select update from branch and choose the branch from which you like to merge changes.
- Distribute to branch: select the branch containing the new changes/features, select distribute to branch and choose the branch to which you like to merge changes.
When merging a branch that contains more than one revision since the previous merge, all these revisions are displayed in bold to indicate that you can choose any one of them to merge.
If you select one, all changes of the intermediate revisions between the selected branch and the previous merge will automatically be included in the merge.
Discard changes
On the bottom of the screen you will find a checkbox Discard changes. Check this option to merge branches without changes. This can be helpful when in the example above you do want to merge change V4, but not V2 and V3. This can be done by first merging the branches by selecting revision V3 and check the option Discard changes. Next merge again, selecting revision V4 and don't check the option Discard changes.
Note that changes that have been set to discard changes in the past cannot be merged later on.
In case you accidentally ticked discard changes but you still want to acquire these changes you have to create a temporary branch in which the changes are taken over and merge that one to the destination branch.
Conflict resolution
When you want to merge two branches it is possible that conflicts arise. This happens when a specific element is changed or created in both branches. The system cannot decide which change is leading so you will have to solve each conflict manually. Before the actual merge takes place, a list of conflicts is presented. If you decide to continue the merge, you will have to open the updated branch in order to resolve the conflicts.
When you open a branch that has unresolved conflicts, a message will appear at the bottom of the screen.
Clicking the message will open a window with a list of all conflicts. You can also open the list of conflicts from within a project. Open the backstage menu by clicking the ‘File’ option and select ‘Conflicts’
There are four different types of conflicts:
- Duplicate name conflict: Two objects with the same name were created in the same module but in different branches. This conflict can also occur if you rename objects. In this case, both definitions are available in the domain for you to inspect.
- Content conflict: The same object was updated in 2 different branches, but the update was not the same. You have to choose which definition you want to keep.
- Delete conflict: An object was deleted in a branch, while in the other branch the object was edited.
- Parent conflict: In one branch the complete module was deleted, while in the other the definition of an object has changed. If you decide to keep the new object definition, you will again get the module, but with only the new definition inside it.
In case there is a duplicate element, the object will have two definitions after the merge: the 'originalname' object is renamed to 'originalname_other'. To resolve the conflict you must select one of the definitions and update it to your liking and remove the other object. The system aids in this conflict resolution process by letting you compare both definitions.
To compare the definitions you can either open one of the object definitions, and select the conflict button on top of the object editor. This will show you the conflict message and allows you to open the compare window.
Or you can open the list of conflicts via the backstage view or the conflicts message. This gives you a complete overview of all conflicts in this project and the option to open a compare view for each conflicting object.
The object compare view shows both definitions side by side. Differences in the definition are indicated by an icon at the specific properties. You can select and edit one of these definitions to resolve the conflict.
Once you have selected one of the definitions you can use the view selector to change the view from a side-by-side view to a view where both definitions are placed on top of each other. This later view is more convenient for large and complex editors such as flows or documents.
By using the slider you can gradually see the other definition appearing. Editing can only take place in the selected definition.
After solving the conflicts, each conflict should be marked as resolved on the conflict list and the list must be saved.
Overview
Content Tools