Version Control

Dividing the API into several versions is necessary for improvement without compromising backward compatibility. On one hand, new needs constantly arise and changes must be made; on the other hand, any change to the interface can break the functionality of existing plugins. To resolve this dilemma, the history of API development is divided into versions: at a certain point, the development of the next version is halted, the interface is fixed, and further development continues within the next version. Whatever changes are made in the future, the plugin developed for the fixed version will function properly until that version is no longer supported.

Version Lifecycle

Large LTS versions (from Long-Term Support) are released approximately every two years and are supported for about four years. Between them, intermediate preview versions are released every three months and are supported for 3 versions of SyrveRMS. Thus, at any given time, the two most recently released LTS versions, the three most recently released preview versions (or two if an LTS version was released in the previous 9 months), and a developing LTS version available for review are supported.

LTS versions are numbered sequentially with whole numbers — V1, V2, V3, V4, V5, V6, and so on. Preview versions are interim states of the developing LTS version, so they contain the number of the developing LTS version in their name and are numbered sequentially with the prefix “Preview”, for example, during the development of V9, versions V9Preview1, V9Preview2, and so on will be released until V9Preview7, after which V9 itself will be released.

Release Schedule

After the release of the next LTS version, roles are redistributed as follows:

• support for the deprecated version is discontinued;
• the version that was stable is declared deprecated;
• the version whose development has been completed is fixed and becomes stable;
• a new developing version appears.

The cycle of preview versions is slightly simpler:

• support for the deprecated preview version is discontinued;
• the current preview version is declared deprecated. If there were two current preview versions, the older one is declared deprecated;
• the interim state of the developing LTS version is released as the new current preview version.

Choosing a Version

By default, it is recommended to use the stable LTS version, as this will minimize the effort required for migration to new API versions. If new features that are not yet available in LTS versions are needed, it is recommended to use the current preview version; in this case, migration between preview versions will be necessary every 3-6 months until the next LTS version is released. It is better not to start development for versions declared deprecated, as this is unpromising; these versions are supported only for backward compatibility during the period when a new API version has already been released, but plugins have not yet transitioned to it. Using the developing version is not recommended, as its interface is not yet fixed, backward compatibility is not guaranteed, and any changes are possible. This version is available for exploring new features and for early plugin development for the future API version, so that by the time it is released, a ready or nearly ready plugin providing new capabilities is available.

The API version for which the plugin is developed is determined by the version of the interface IFrontPlugin that it implements. For example, if the plugin references the assembly Resto.Front.Api.V6.dll and implements the IFrontPlugin interface from this assembly, it is a V6 plugin.

It is assumed that the V6 plugin uses the API interface of version V6. However, if necessary, the plugin can simultaneously use all supported API versions. Considering that starting from V6, the namespaces do not contain the API version number, to avoid collisions between types with the same name from different assemblies, it will be necessary to use extern alias. For example, to access an operation that appeared only in V7Preview2 from a V6 plugin, in addition to the usual reference to V6, it is necessary to add a reference to V7Preview2 with the alias V7Preview2, and then extract the service V7Preview2::Resto.Front.Api.IOperationService from PluginContext.Services. The PackageReference mechanism supports extern alias starting from Visual Studio 2019 16.7. Important: do not implement interfaces IFrontPlugin of different versions simultaneously; such a plugin will not be loaded.

Compatibility of SyrveRMS Versions and API Versions

¹ Version V6Preview4 was experimental, released at the beginning of the SyrveRMS 6.4 development cycle. Additionally, V6Preview6 and V6Preview7 were skipped, and the LTS version V6 was released instead. ² Version V7Preview2 was released late as 7.3.5 (instead of 7.2). ³ Support for version V7Preview7 was extended to 8.6 inclusive due to issues with auto-updating plugins from V7Preview7 to V7. ⁴ The lifespan of Preview versions starting from V8Preview4 has been extended by one SyrveRMS version.

Starting from SyrveRMS version 8.5, the support cycle for Preview versions is extended: version V8Preview4, which was released in 8.3, will only be removed in 8.6, i.e., it is supported in 8.3, 8.4, 8.5.

Backward Compatibility

Backward compatibility guarantees that a plugin developed for a specific API version will work the same with any versions of SyrveRMS that support that API version.

Software Compatibility

Software compatibility prohibits changes to the public interface — data structures, method signatures, and so on must be fixed. It is clear that if a public class or method is removed, the plugin will fail to compile with the new SDK, and a plugin compiled under the old SDK will crash during runtime (TypeLoadException, MissingMethodException, etc.). There can also be less obvious violations of backward compatibility. However, if we disregard exotic cases, in practice, adding a new class, property, or method can be quite safe. This allows for the use of new features without waiting for the next release. With this in mind, the current policy is:

• in LTS versions, no changes after release, because every public change is a breaking change,
• in preview versions, almost certainly backward-compatible changes to the public interface are possible.

Changes in Behavior

In general, changes in the behavior of released API versions are not allowed. If a function worked under certain conditions, it will continue to work, and if it did not work, it will continue not to work. The exception is destructive API usage scenarios, where the consequences are worse than violating backward compatibility. For example, if due to a vulnerability in the API, erroneous actions by the plugin could lead to data corruption or stop the operation of the SyrveFront application, then the API will include appropriate protection. This will not be considered a change in behavior, as correctly functioning plugins will not notice any changes.

Support Duration

The duration of support for a specific API version refers to the period during which updates to SyrveRMS are released that support that API version. There is no calendar limitation in the SyrveRMS product on the ability to use a particular API version. All API versions supported by a specific build of SyrveRMS are supported indefinitely. Thus, if a SyrveRMS user does not update, they can theoretically continue to use old plugins for as long as they want. However, in practice, users are forced to update SyrveRMS for compliance with changes in legislation, new features, and bug fixes, which means that plugin developers must timely release updates compatible with new API versions.