Updating to a new Library Version

You can supply new versions of a library as described on Updating Libraries and Administrating Libraries. If a new version is available, users can change their services to use the new version as described on Updating Libraries > Switching Between Library Versions.

Before updating a library to a new version, you should consider how the changes to that library that come with the new version may affect your service. Carefully read the release notes of the library to understand what has changed.

This is the reason why a library owner should supply release notes - at least in the description of the library, e.g. in a tabular way.

Updating the version of a library in a Designer service triggers the validation. Breaking changes from the library will be reported directly in the validation panel. In most cases you can click on the validation error to find the source of the error.

Generally, if possible, a library owner should avoid changing a library in a way that breaks the interface.

If a breaking change cannot be avoided, a good handling of breaking changes may look like the following:

Do not delete an outdated operation but deprecate it, e.g. in the library documentation.
If you want to delete it at some point, announce the end-of-life of this operation before deleting it in an upcoming version. This gives the library users time to prepare.
Instead of introducing new parameters to existing operations, create a new operation for that.
Give library users migration hints in the release notes of your library.

Understanding Library Changes

The table below lists possible changes and their effect on the usage service.

Library Element	Type of Change	Errors	Impact
Class	new	-	A new class/type has no impact on the library usage.
	removed	The missing type is indicated as Unknown type on your canvas. `Found an element referencing a class that has not been imported.`	If interface elements have been removed, you cannot use them anymore and you need to remove them from your implementation. Looking at the library documentation, you may find a new type you can use as a replacement.
	changed name	The missing type is indicated as Unknown type on your canvas. `Found an element referencing a class that has not been imported.`	Changing the name of a class is the same as removing it and adding a new one. You need to adjust your implementation to use the new type.
Property	new	-	New properties to a class have no impact on the library usage.
	removed	`Attribute '<a property>' is not defined on class '<a library class>'.`	If interface elements have been removed, you cannot use them anymore and you need to remove them from your implementation. Looking at the library documentation, you may find a new property you can use as a replacement.
	changed name	`Attribute '<a property>' is not defined on class '<a library class>'.`	Changing the name of a property is the same as removing it and adding it as a new one. You need to adjust your implementation to use the new property.
	changed type	`Trying to assign '<something>' (type = '< a type>') to '<a property>' having the incompatible type '<another type>'.`	You need to adjust your implementation so that it takes the new type into account.
Operation	new	-	New operations have no impact on the library usage.
	removed	The missing operation is indicated as Unknown operation on your canvas. `[VALXUML] Attribute '@calledOperation' on element 'nodes' has no (non-empty) value.`	If interface elements have been removed, you cannot use them anymore and you need to remove them from your implementation. Looking at the library documentation, you may find a new operation you can use as a replacement.
	changed name	The changed operation is indicated as Unknown operation on your canvas. `[VALXUML] Attribute '@calledOperation' on element 'nodes' has no (non-empty) value.`	Changing the name of an operation is the same as removing it and adding it as a new one. You need to adjust your implementation and find the operation that replaces the used one.
Parameter	new	The operation of the new parameter is indicated as Unknown operation on your canvas. `[VALXUML] Attribute '@calledOperation' on element 'callActions' has no (non-empty) value.`	The operation is treated as changed operation because the interface has changed. You need to re-add the operation to the canvas with the new parameters.
	removed	The operation of the new parameter is indicated as Unknown operation on your canvas. `[VALXUML] Attribute '@calledOperation' on element 'nodes' has no (non-empty) value.`	If interface elements have been removed, you cannot use them anymore and you need to remove them from your implementation. You need to re-add the operation to the canvas with the changed parameters.
	changed name	The operation of the new parameter is indicated as Unknown operation on your canvas. `[VALXUML] Attribute '@calledOperation' on element 'nodes' has no (non-empty) value.`	Changing the name of a parameter is the same as removing it adding a new one. You need to re-add the operation to the canvas with the changed parameters.
	changed type	The operation of the new parameter is indicated as Unknown operation on your canvas. `[VALXUML] Attribute '@calledOperation' on element 'nodes' has no (non-empty) value.`	Changing the type of a parameter leads to the listed error in your usage service. You need to adjust your implementation so that it takes the new type into account.

Related Pages: