Model version management

Perspectives Models have version numbers that follow the Semantic Version standard - but only the MAJOR and MINOR parts are explicit in the version number. We leave patches out but represent them in another property than the Version itself. This is because

  • we are not interested storing successive patches

  • an installation updates automatically whenever a new patch is available.

Creating a new major or minor version

To start work on additional functionality (minor version) or backward incompatible changes (major version), create a new VersionedModelManifest. We’ll call this the workversion. Make sure that the current version in use is marked as the recommended version!

Now develop the workversion, re-building it until it is ready. To publish it, mark it as the recommended version.

Automatic installation of patches

The System model contains a calculated role ModelsToUpdate that would hold instances of the ModelsInUse role with a (locally) stored patch number that is lower than the patch number of the VersionedModelManifest (in the Repository) that fills it. There is a context action of the System User to update all these models (i.e. to locally install the highest patch). However, on system startup, these models are updated automatically. Thereafter they will not appear in ModelsToUpdate. The user is notified by these updates.

Also notice that when a public resource changes after a particular installation has fetched it from the server, it will not show up in ModelsToUpdate (nor be automatically updated) until it is removed from the installation’s cache. This can be forced by re-starting MyContexts.

Patching a recommended version

When a version should be patched, the author may need several build cycles before a satisfiable state of the model is reached. It should be avoided that end users update their local installation with one of the intermediate builds. The author should follow the following procedure to avoid this:

  • create a new VersionedModelManifest with Version MAJOR.MINOR.dev (we call this the workversion). Do this in the official repository. Give this the source of the recommended version;

  • take this model into use on the development machine in a test installation of MyContexts;

  • upload new versions of the model in the workversion, test it on the development machine, until it is ready;

  • now upload the patched source code in MAJOR.MINOR.dev to the recommended version (MAJOR.MINOR);

  • increase the patch number in MAJOR.MINOR. This will eventually cause all user installations to be updated;

  • take the recommended version into use in the test installation;

  • finally, remove the workversion from the repository.

Automatically installing builds

On uploading and succesfully compiling a new version of a model source text in CouchdbManagement, the Build property of the manifest is automatically increased. The previous DomeinFile is overwritten. DomeinFile names just include the MAJOR.MINOR part of a SemVer, like joopringelberg_nl-JoopsModel@1.4.json.

Boolean property UpdateOnBuild can be set to true for any installed model. Subsequently, when the author creates a new build of that particular version, it will be installed automatically on all machines that have this property set. Do this, as developer, for the testmachine.

↑ Up: Developing Perspectives and MyContexts | Next: When the shape of the DomeinFile changes →