Versioning of Services

Versioning is the process of assigning a unique version number to a unique state of your service. And versioning is an important topic to consider when you develop services in the Designer. Refer to Versioning of Libraries for more information on the specific requirements of library versioning.

If you deploy a service in the Designer, 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):

Good to Know: What is SemVer format?

Semantic Versioning (SemVer) is one of the most common versioning methods. It helps users to understand whether they can update without any problems. The SemVer format consists of three numbers: major.minor.patch, e.g. 1.0.1.

Service with API (e.g. REST)

The major number indicates that the Service API has breaking changes. Customers must adapt the changed API.
The minor number stands for new features but the Service API has no braking changes. Customers do not have to make changes.
The patch number indicates all other non-breaking changes.

Service or Application without API

The major number has no special meaning. In this case, you can use the current year (24 or 2024), for example, or increase the number for special milestones.
The minor number stands for new features, improvements and bug fixes.
The patch number indicates that the version only contains bug fixes.

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

Working with Versions

Versioning ensures that the entire team is able to recognize the level of development they are working with. Especially for bugfixing it is crucial to be able to retrieve and run different versions of the software to determine in which version(s) the problem occurs.

If you meet problems in your versioned services, you have two options

Compare different versions to see the differences between them. To do so, import a previous version and compare the versions manually.
Go back to previous versions to find out in which version a bug has been introduced into the service.

Create Your Own Change Log!

In both scenarios a change log is a useful companion. We recommend to create a change log for each version of a service in which you summarize the most important changes. For services, we recommend to add the change log in the service description (refer to Designer Guide > Service Configuration Details). 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 services 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 service versions, you must create and save exports of different states of your services. You should create a new version at least after every milestone reached.

Creating a Service Version

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

(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 service 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 service as .zip file. You can use this file for a later import. Use option Compiled > Service to export the compiled service as .rep 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 service
- Add the version number 1.0.0
- Add a change log to the service description: Initial version of myService. Main functions ….
- Export the service and name the exports myService_1.0.0.zip and myService_1.0.0.rep
You add a feature to your service
- Change the version number to 1.1.0
- Add an entry in the change log that describes the new feature
- Export the service and name the exports myService_1.1.0.zip and myService_1.1.0.rep
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 service and name the exports myService_1.1.1.zip and myService_1.1.1.rep

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

Import the .zip file via the Explorer context menu to get access to your project including all models, forms and implementations (refer to Designer Guide > Exporting and Importing Explorer Contents).
To deploy the service to a test or production system, use the .rep file along with the deployment wizard in the PAS Administration (refer to Administration Guide > Working with the Deployment Wizard for details).

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.

Related Pages: