Versioning of Libraries

Versioning is the process of assigning a unique version number to a unique state of your library. And versioning is an important topic to consider when you develop your own libraries in the Designer.

You want to develop your own libraries in the Designer? Check out our recommendations for Library Development.

If you develop a library in the Designer, you create a separate Designer service (refer to Designer Guide > Developing and Using Libraries). Therefore, you must enter a version number in the deployment controls (refer to Designer Guide > Service Deployment Details for more information). The version number must be compliant with SemVer format (major.minor.patch):

If you have made changes to a library, you should not upload it again under the same version name. This can lead to problems in the Designer. Therefore, we recommend to work with pre-release tags during the development phase. For example, you can add a suffix to the release version like 1.1.0-alpha. When the library development is finished, delete the tag and use the version as the official library version number: 1.1.0.

On this page we have compiled the most important considerations on the subject of versioning libraries in Scheer PAS Designer.

Working with Versions

In the Designer, working with libraries only becomes cumbersome and confusing if you install too many library versions. We recommend keeping the number of installed versions as low as possible.

If you meet problems in your versioned libraries, you have two options:

1. Compare different versions to see the differences between them. To do so, import a previous version and compare the versions manually.

2. Go back to previous versions to find out in which version a bug has been introduced into the library.

Create Your Own Change Log!

A change log is a useful companion. We recommend to create a change log for each version of a library in which you summarize the most important changes. For libraries, you can use the description field in the asset wizard (refer to Designer Guide > Documenting Assets). Create a table with at least: Version number and description. Also useful: Date and name of the author. If you use a ticket system for development, also add the ticket number(s).

Using Source Code Management Systems

A source code management system (SCMS) like git can help you to store the Designer libraries and to create a change log. In the case of git, you use tags to mark commits that relate to a specific version and commit messages to document your changes.

Versioning of Services: How does it work?

If you want to be able to compare different library versions, you must create and save exports of different states of your libraries. You should create a new version at least after every milestone reached.

Creating a Library Version

Use the export functionality in the Designer to save a version of your library.

(1) Before you start the export:

• Increase the version number: If you reach a development milestone, you should change the version number. The SemVer format is also a good guide to when it is worth saving a new version.

• Update your change log (see above) in the library description. Add at least one entry in the change log.

(2) When this is done, go to the Controls panel in the Designer and open the additional menu. Use option Designer Service to export the library service as .zip file. You can use this file for a later import. Use option Compiled > Library to export the compiled library as .xlib file.

• Give your exported files unique names (use the unique version name to be able to distinguish exports from others at a glance).

• Store both files in a central location.

Example:

• You finish the initial version of your library

  • Add the version number 1.0.0

  • Add a change log to the service description: Initial version of myLibrary. Main functions ….

  • Export the library service and name the exports myLibrary_1.0.0.zip and myLibrary_1.0.0.xlib

• You add a feature to your library that does not change the interface

  • Change the version number to 1.1.0

  • Add an entry in the change log that describes the new feature

  • Export the library and name the exports myLibrary_1.1.0.zip and myLibrary_1.1.0.xlib

• You fix two bugs

  • Change the version number to 1.1.1

  • Add an entry in the change log that describes the bugfixes

  • Export the library and name the exports myLibrary_1.1.1.zip and myLibrary_1.1.1.xlib

You can now use the exported files to switch back to an older version of your library at any time:

• Import the .zip file via the context menu of the Explorer to gain access to your library project and be able to develop it further (refer to Designer Guide > Exporting and Importing Explorer Contents).

• Import the .xlib file via the Designer Administration menu Libraries to be able to add the library to services and use it within them (refer to Designer Guide > Administrating Libraries).

Only upload released libraries to namespace Shared!
The upload to this namespace makes the library also available to all users of the system via the asset drawer. Refer to chapter Sharing Designer Content in the Designer guide for detailed information.

Limitations of Versioning

Versioning is not a solution for missing collaboration processes. PAS does not provide tools for merging different versions, so you still need to coordinate the collaboration of all team members working on the same project. The team can only work together on one version at a time, for example on 1.0.0, then together on version 1.1.0 and so on.

The following scenario is currently not supported in PAS: Developer A is working isolated on version 1A, then 2A etc. and developer B is isolated working on version 1B etc. and if both are ready version A and version B are merged to version 2AB with the help of a merge tool.