Assigning a version to your applications

In CICS TS, certain resources have versions associated with them. For example, an application in the context of cloud enablement requires a version and a name. A version must also be specified for a CICS bundle that is to be installed as part of either a CICS application or a CICS platform. CICS application bindings have a version too. These versions are different to the CICS product version, such as Version 5. Why is this version needed, and how should you use it?

You must apply a versioning policy to your CICS® bundles, application bundles, and application bindings to deploy and manage updates in the CICS environment. You cannot use an existing version of an application bundle to install new versions of the CICS bundles for the application, and you cannot use an existing version of an application binding with a new version of an application bundle. You must update the versions of the application bundle and application binding whenever you update the CICS bundles for the application.

For cloud enablement, CICS suggests a versioning system based on semantic versioning, described in the technical paper Semantic Versioning. This versioning system is widely used in OSGi-based projects, such as Eclipse, and was first seen in CICS V4.2 with the Java class library for CICS (JCICS) API where it enables the author of an API or service to clearly describe the nature of a change in the implementation, so clients can understand any compatibility issues with earlier versions.

The version attribute used for a CICS TS application, a CICS bundle, or an OSGi bundle takes the form <major>.<minor>.<micro>: for example, 2.3.1 The version should be updated manually by whoever is responsible for maintaining the resource concerned, for example, the application developer. The version should be the first change made as part of a new activity.

The version part changes should be used in the following ways:

Micro: For example, from 1.0.0 to 1.0.1. No external change (for example, a bug fix).
Minor: for example, from 1.0.1 to 1.100.0. Compatible with an earlier version or an external change (for example, existing clients are unaffected).
You might choose to increment the minor version by 100 instead of by 1. This technique is valuable when you want to run multiple versions of an application simultaneously. For example, take a scenario where you run version 1.0.0 of an application is in production and you add in version 1.1.0. For a while, both versions run at the same time without problems. Then, a bug is found in version 1.0.0 that requires a small change to the externals of the application. Ideally, you would increase the minor version number, because the externals have changed, but V1.1.0 is already in use. If you use version 1.100.0 when you added the new version of the application, you could fix the bug in V1.0.0 and increased its minor version number to reflect the change to the externals of the application. This technique is used by CICS TS to version the OSGi bundles that are included with the JCICS APIs.
Major: For example, from 1.100.0 to 2.0.0. Change is incompatible with earlier versions (for example, a different format of file records or an operation is removed.)

When you change the version of an application, according to the principles of semantic versioning, the new version should reflect the largest change in a CICS bundle that is included in the application. For example, you might change one CICS bundle for an application from Version 1.0.1 to Version 1.0.2, which is a micro version change, and change another CICS bundle for the application from Version 1.2.0 to Version 1.3.0, which is a minor version change. The application bundle that includes these two CICS bundles should therefore have a minor version change, so if the application was previously at Version 2.5.1, it should change to Version 2.6.0.