Upgrading Model RealTime version in a multi-stream environment

Upgrading IBM Model RealTime to a new version is a straight-forward process and only requires the new version to be deployed to all users. However, if the storage format of the new version is different from the old version, special considerations are needed. In this article, we discuss what to keep in mind when moving between Model RealTime versions that use different storage formats. In particular, we look into some best practices for large user groups using Model RealTime for development in a multi-team and multi-stream context.

Tool Basics

The key rules to keep in mind when discussing Model RealTime and model format versions are the following:

These rules apply when loading models interactively in the tool, when loading models for batch processing (like code generation), and when loading models implicitly (such as when comparing or merging).

Simple Case - One Team, One Stream

Before looking into how to handle a larger organization, it is beneficial to look at a simple scenario when a small team working on one development stream performs an update of tool version. In principle, the workflow is the following:

  1. Distribute the new tool version to all involved developers in the team.
  2. Upgrade the models to the new storage format (see Upgrading Model RealTime models to a new version).
  3. Check the changed models into the development stream in your CM system.
  4. All developers: Check out the updated version of the model and start using the new version of Model RealTime.

However, even in a simple case, there are some aspects to take into consideration. First, realize that a new tool version that implies a model format upgrade typically involves a change in tool functionality. So, it is highly recommended to check the release notes for the intermediate versions before migrating. Next, consider that code generation might have changed and it is highly recommended to ensure that external code integrating with the generated code still works. In general, it is important to review all integration aspects of the usage of Model RealTime before doing the upgrade. Are any tools integrated with Model RealTime? Are the tools compatible with the target Model RealTime version?

These aspects make it necessary to view a model version upgrade, even for a fairly small team, as a two step activity:

  1. Perform a trial migration activity, simulating the most essential aspects of the real migration as closely as possible.
  2. Perform the actual model migration as outlined above.

The trial migration activity is recommended to consist of at least the following actions:

Multi-Stream Projects

A common situation is that a development project needs to manage different streams or branches in the source code management system. A typical development situation might have:

In the context of migrating from an old version to a new version of Model RealTime, where the storage format has changed, the constraint on merge direction has implications for what can be done. As discussed previously, merge is only possible from a stream using an older version to a stream using a newer version:

In practice, the sequence of actions needed when migrating to a newer version of Model RealTime requiring a storage format upgrade in a multi-stream project is to follow the steps below:

  1. Make the new version of Model RealTime available to all team members.
  2. Migrate the master stream to the new version of Model RealTime.
  3. Migrate all feature streams to the new version of Model RealTime before merging from the master stream.
  4. Optionally migrate maintenance streams.

Multi-Component Projects

In a large project, it is common to have several different components, each consisting of a number of model projects. The components might contain projects that depend on projects in other components, forming a dependency graph between components. An additional layer or complexity is that different sets of components can be used to create different end products with different release schemes. To manage this complexity, it is common to use a layered approach with one or more "platform" or "library" components that are reused in a number of products together with product specific components or "application" components.

To manage this structure, when moving to a new version of Model RealTime that requires an upgrade of the storage format, use the ability of Model RealTime to convert model versions when loading a model. While the "platform" components remain in the older storage format, the "application" components are upgraded to a newer version. Only when all application components have moved to the newer storage format should the platform components be migrated. During the transition phase, the application components are developed using the newer version of Model RealTime while the platform components are developed using the old version.

To give a smooth workflow when working with the application projects, it is necessary to overcome the problem that Model RealTime tries to migrate the platform components when loading them into the tool. The default behavior is that it prompts the user loading the models, asking if profiles should be upgraded. This can be controlled by preferences on the "Modeling" preference page, under the "Profile migration" section of the page. The recommendation is based on making sure (either using the source code management system, using scripting, or by some other means) that all platform model files are read-only when working with product specific application models. Then change the preferences as follows:

The result is that the platform models are loaded without prompting and the tool does not try to migrate them to a newer version.

Migrating from a New Version to an Older Version

Model RealTime has no built-in support for moving a model to an old storage format. However, there might be a possibility to do this if it is necessary, on a case-by-case basis. In some situations, this can be done with a utility script provided on demand from IBM.