Versioning

Language:

rad interfaces are versioned for the following reasons:

APIs change over time.
A change to an API might be incompatible with existing consumers.
A change might be compatible with existing consumers but new consumers might not be able to use the API that was in place before the change occurred.
Some features represent committed interfaces whose compatibility is paramount, but others are private interfaces that are changed only in lockstep with the software that uses them.

Numbering

The first issue is measuring the compatibility of a change. rad uses a simple major.minor versioning scheme. When a compatible change to an interface is made, its minor version number is incremented. When an incompatible change is made, its major version number is incremented and its minor version number is reset to 0.

In other words, an implementation of an interface that claims to be version X.Y (where X is the major version and Y is the minor version) must support any client expecting version X.Z, where Z <= Y.

The following interface changes are considered compatible:

Adding a new event
Adding a new method
Adding a new attribute
Expanding the access supported by an attribute, for example, from read-only to read-write
A change from nullable to non-nullable for a method return value or readable property, that is, decreasing the range of a feature
A change from non-nullable to nullable for a method argument or writable property, that is, increasing the domain of a feature

The following interface changes are considered incompatible:

Removing an event
Removing a method
Removing an attribute
Changing the type of an attribute, method, or event
Changing a type definition referenced by an attribute, method, or event
Decreasing the access supported by an attribute, for example, from read-write to read-only
Adding or removing method arguments
A change from non-nullable to nullable for a method return value or readable property, that is, increasing the range of a feature
A change from nullable to non-nullable for a method argument or writable property, that is, decreasing the domain of a feature

Note - An interface is more than just a set of methods, attributes, and events. Associated with those features are well-defined behaviors. If those behaviors change, even if the structure of the interface remains the same, a change to the version number might be required.

Clients and Versioning

A rad client can access version information from a client binding. The mechanism for accessing the information depends on the client language like C, Java and, Python. For example in Python, the rad.client module contains the rad_get_version() function which may be used to get the version of an API.