Versioning & Releases

This article describes how to create multiple versions of a program (= multiple releases) and how versioning in drag&bot works in general.

Advanced use case

This is a more advanced use case of drag&bot and if have just started you may want to skip this article.

What is a program version?

In drag&bot program versions are used to keep track of different development states of a program.

Default behavior

By default you will only have one version of a program. Each time you press Save the program will be overwritten.

The version will be v1-pre and only the internal version will be increased on each save (more about pre versions)

Logic behind the version number

The version number is based on semantic versioning. This means it is a three-part version consisting of major version, minor version and patch.

Version format: Major.Minor.Patch, e.g. 1.0.0

In drag&bot each part of the version is increased in the following way:

• The Major version is increased when the input or output parameters of a program changes (more about major versions)
• The Minor version is increased after a program was released
• The Patch is increased when creating a patch of an existing release

Pre versions

Programs that are not (yet) released have a so called "PRE" version. The version number contains a -pre postfix and the pre version number, e.g. 2.1.0-pre.2. The pre version number is increased each time a program is saved.

Major versions and version compatibility

As described above, the major version of a program will be increased, when inputs or outputs are changed or the errorcodes of a program changed (detailed list below). This is done to give an indicator about the compatibility of this version.

When a program is used as a subprogram, it is not updated automatically to a newer major version, because the parameters are not compatible. However it can be updated in the dependency overview on the Information tab.

Changes that lead to a major increase

• Adding or removing inputParameters or outputParameters
• Changing the following parameter fields (alphabetically):
  • availableOptions (Adding or removing)
  • constraints
    • Adding or removing
    • Changing the rule field
  • dataType
  • parameters (Adding or removing)
  • paramId
  • title
  • type
  • unit
• Adding or removing errorcodes

Save or Release a program?

• Save overwrites the current program
• Save as new copies the current program
• Release as X.Y.Z creates a release of a program which is not meant to be changed anymore

Copying vs Releasing

Copying a program will create a complete new list entry in the program overview and the copy is completely separated from the original program. (Internally there is a new identifier for this program.)

Releasing a program captures the current program in a state that cannot be changed. When having multiple releases of a program, other programs that use it as a subprogram, will always use the newest (compatible) version of this program by default. And it's also possible to use a specific release version (see below).

View releases in the Program Overview

Programs with releases have a "Releases" button on the right:

Clicking Releases opens the list of all releases of this progam:

Use the action buttons to manage each release.

Create a patch of an already released program version

You can also edit releases. However the original releases will not be changed, but a patch release will be created instead.

Release patch X.Y.Z creates a new patch for this release

Patches for small changes

Use patches only for small changes, e.g. adjusting a parameter or changing metadata like names. For bigger changes work with the newest version of the program or create a copy of the release.

Cleaning up

After creating a patch you might want to delete the previous release in order to clean up. The patch release is a independent program version and you will only need the older version, in case you want to explicitly use that one too. You can learn more about using a specific version below.

Use a subprogram with a specific version

When building a program in the Builder and adding function blocks or subprograms, the newest version of a program will be used by default. Once a block is added, it will update automatically, in case there is a newer version available that has the same major version.

Function blocks with multiple versions/releases have a drop-down list, with which you can select a specific version. Then always this exact version will be used. Only in case this version has been deleted, the newest compatible version will be used.

Update a function block or subprogram to a newer version

If there is a newer major version of a function block or subprogram, there will be an indicator at the Information tab inside the Builder.

In the dependency list on the Information tab, click on Update to newest on the dependency you want to update.

A dialog will open, showing the status of the update and a list of differences between the two versions.

There are three possible states:

• "Green" - Automatic update possible: only minor changes, like change of displayTitle or description
• "Yellow" - Review differences: changes can be applied automatically, but they change the semantics of the program, and you might need to do slight adaptions after applying the changes, like setting the values of a new paramater or reselecting a new option after one has been removed
• "Red" - Automatic update not possible: there are too many differences to update automatically. If you still need the new version, you can use the "Force update" option, however this will reset the values of all parameters of this function block

After you have reviewed the changes, you can Apply them.

Affected function blocks

Additionally to the differences, there is also a list of affected function blocks. The list shows all function blocks on which the changes will be applied.

There can be multiple affected function blocks, if you have used a dependency multiple times. E.g. if you use the "Move Cartesian" for a "Move to machine" and a "Move to home position".