This document refers to the Runtime interface defined in packages/teams-js/src/public/runtime.ts. The runtime object describes the capabilities and configuration of the host and is versioned so that the teams-js library may parse older versions of the runtime. The following information describes when and how the Runtime version should be updated.
A major version change is one by which it is impossible to either upgrade from the previous version to the next version or downgrade from the next version to the previous version without losing functionality. For example, if capabilities x and y are merged into a new capability z, then we cannot determine if z is supported in the new version unless both x and y are supported in the previous version. If x but not y was supported in the previous version, then z must be defined as unsupported in the next version and all functionality covered under x is lost despite no changes being made to the host’s functionality. Similarly, if a capability is split into two different capabilities then we cannot determine if that capability in the previous version is supported based on the capabilities in the next version.
A minor version change is one by which the previous version can be transformed into the next version and back without any loss of teams-js functionality.
- Yes – new minor version is required number if this property can be generated by App SDK without loss of some previously supported functionality, new major version is required if some previously supported functionality is lost when this property is not provided by the host.
- No new version is required.
- Yes – new minor version is required.
- Yes – new major version is required.
- Yes – new major version is required.
- Determine if a major or minor version change is required
- Update
latestRuntimeApiVersion
in runtime.ts to the new version number - Create new interface that extends IBaseRuntime and has apiVersion set to the new version (
IRuntimeVX_Y extends IBaseRuntime { apiVersion: x.y; ... }
) - Set type alias Runtime to the new runtime interface (
type Runtime = IRuntimeVX_Y
) - Add an
IRuntimeUpgrade
to theupgradeChain
that will transform the previous runtime version to the new one - Update "runtime versioning" tests in
packages/teams-js/test/public/runtime.spec.ts
to use new version number - Add a test for upgrading from the previous runtime version to the new one
The documentation on the mapTeamsVersionToSupportedCapabilities
structure should generally help answer this question. That said,
if you are adding a new capability and it will be supported by any version of TeamsV1 or Teams Mobile, you will need to update the
mapTeamsVersionToSupportedCapabilities
structure to indicate which version and which platforms support your new capability.