Difference between revisions of "Version Migration"

From Developer Documents
Jump to navigation Jump to search
 
(8 intermediate revisions by the same user not shown)
Line 17: Line 17:
 
All shared concepts contained in the ontology are accordingly versioned along with the ontology and the version number is visible in the URI. For ontological concepts we define
 
All shared concepts contained in the ontology are accordingly versioned along with the ontology and the version number is visible in the URI. For ontological concepts we define
  
'''versioned URI''' as the proper URI of the resource e.g.  <nowiki>http://www.simantics.org/Layer0-1.0/ConsistsOf</nowiki>
+
* '''versioned URI''' as the proper URI of the resource e.g.  <nowiki>http://www.simantics.org/Layer0-1.0/ConsistsOf</nowiki>
 
+
* '''unversioned URI''' where version information is omitted e.g.  <nowiki>http://www.simantics.org/Layer0-0.0/ConsistsOf</nowiki>
'''unversioned URI''' where version information is omitted e.g.  <nowiki>http://www.simantics.org/Layer0-0.0/ConsistsOf</nowiki>
 
  
 
Ontologies are deployed as OSGi bundles. Declarations in Simantics software may use the unversioned URI to refer to concepts in the ''latest'' version on an ontology (or the version found from OSGi dependencies). An utility class for converting between '''versioned URI''' and '''unversioned URI''' is defined in class '''org.simantics.scl.reflection.OntologyVersions'''.
 
Ontologies are deployed as OSGi bundles. Declarations in Simantics software may use the unversioned URI to refer to concepts in the ''latest'' version on an ontology (or the version found from OSGi dependencies). An utility class for converting between '''versioned URI''' and '''unversioned URI''' is defined in class '''org.simantics.scl.reflection.OntologyVersions'''.
Line 25: Line 24:
 
Additionally we define
 
Additionally we define
  
'''working ontology''' as an ontology bundle which is under development
+
* '''working ontology''' as an ontology bundle which contains the '''latest''' version of the ontology e.g. ''org.simantics.simulation.ontology''
 
+
* '''released ontology''' as an ontology bundle which is frozen, renamed and never again changed e.g. ''org.simantics.simulation.ontology-1.1''
'''released ontology''' as an ontology bundle which is frozen and never again changed
 
  
 
The following simple rules for ontology development are defined to enable version migration
 
The following simple rules for ontology development are defined to enable version migration
Line 34: Line 32:
  
 
# All ontology versions shall be completely self-contained. All concepts are declared in all versions of an ontology.
 
# All ontology versions shall be completely self-contained. All concepts are declared in all versions of an ontology.
# There shall be exactly one ontology in each ontology bundle.
+
# There shall be exactly one ontology (L0.Ontology) defined in each ontology bundle.
# The '''Bundle-Name''' of an ontology shall be the unversioned URI of the ontology
+
# The '''Bundle-Name''' of an ontology shall be the unversioned URI of the ontology without the '-0.0' suffix e.g. <nowiki>http://www.simantics.org/Simulation</nowiki>
# The '''Bundle-Version''' of an ontology shall be the ontology version as specified in the ontology URI
+
# The first two digits of the '''Bundle-Version''' of an ontology shall be the ontology version as specified in the ontology URI e.g. '1.2'
# The '''Bundle-SymbolicName''' (bundle id) of a working ontology is unchanged when versions grow (e.g. org.simantics.layer0.ontology)
+
# The '''Bundle-SymbolicName''' (bundle id) of a working ontology is unchanged when versions grow (e.g. org.simantics.simulation.ontology)
# The '''Bundle-SymbolicName''' (bundle id) of a frozen ontology is a version-dependent derivative of the id from the working ontology (e.g. org.simantics.layer0.ontology-1.1)
+
# The '''Bundle-SymbolicName''' (bundle id) of a frozen ontology is a version-dependent derivative of the id from the working ontology (e.g. org.simantics.simulation.ontology-1.1)
  
 
==Model Migration==
 
==Model Migration==
Line 46: Line 44:
 
The database can host multiple versions of ontologies which enables old models to exist and to be imported in the database. A typical software feature can only manipulate models defined with the latest versions of some ontologies.
 
The database can host multiple versions of ontologies which enables old models to exist and to be imported in the database. A typical software feature can only manipulate models defined with the latest versions of some ontologies.
  
Software features can make model migration from models created with previous versions of the software. Each model is ''associated in the database with a single software feature version'', which then can be used to determine the actions needed for migrating models to the latest ontological definitions.
+
Software features can make model migration from models created with previous versions of the software. Each model is ''associated in the database with a single software feature version'', which then can be used to determine the actions needed for migrating models to the latest ontological definitions. The version modelling is defined in '''org.simantics.softwareconfiguration.ontology'''.
  
 
The user can browse the old and new models contained in the database and perform model migration at will.
 
The user can browse the old and new models contained in the database and perform model migration at will.
Line 57: Line 55:
  
 
* '''Before the build'''
 
* '''Before the build'''
*# Make copies of all referenced ''working ontology'' bundles in Subversion with frozen ids.
+
*# Make usual tagging and branching of all released plugins in Subversion
*# Change the OSGi dependencies to refer to frozen ontologies accordingly.
+
* '''Right after the build'''
* '''After the build'''
+
*# For all working ontologies which do not correspond to a frozen version : freeze ontology plugin and store as a tag
*# Move back into working ontologies as things change. Increase the version number.
 
 
*# Increment the software version number of models
 
*# Increment the software version number of models
 
+
* '''During modelling when ontology is first modified''' (before this the working ontology was exactly some frozen ontology)
 +
*# Increment ontology version number. (Include the corresponding frozen ontology into product dependencies to enable migration).
  
 
[[Category: Ontology Development]]
 
[[Category: Ontology Development]]
 
[[Category: Database Development]]
 
[[Category: Database Development]]

Latest revision as of 05:19, 3 November 2011

This document addresses the issue of how simantics application migrates from one version to the next. The scope includes software and ontology development.

Ontology Migration

An ontology is a compilation of shared concepts (=types, relations and instances).

   http://www.simantics.org/Layer0-1.0 
       http://www.simantics.org/Layer0-1.0/ConsistOf
       http://www.simantics.org/Layer0-1.0/Library

Ontologies are versioned according to the following scheme

   <Ontology URI>-<major version>.<minor version> 

For example

   http://www.simantics.org/Layer0-1.0 

All shared concepts contained in the ontology are accordingly versioned along with the ontology and the version number is visible in the URI. For ontological concepts we define

  • versioned URI as the proper URI of the resource e.g. http://www.simantics.org/Layer0-1.0/ConsistsOf
  • unversioned URI where version information is omitted e.g. http://www.simantics.org/Layer0-0.0/ConsistsOf

Ontologies are deployed as OSGi bundles. Declarations in Simantics software may use the unversioned URI to refer to concepts in the latest version on an ontology (or the version found from OSGi dependencies). An utility class for converting between versioned URI and unversioned URI is defined in class org.simantics.scl.reflection.OntologyVersions.

Additionally we define

  • working ontology as an ontology bundle which contains the latest version of the ontology e.g. org.simantics.simulation.ontology
  • released ontology as an ontology bundle which is frozen, renamed and never again changed e.g. org.simantics.simulation.ontology-1.1

The following simple rules for ontology development are defined to enable version migration

Modelling rules

  1. All ontology versions shall be completely self-contained. All concepts are declared in all versions of an ontology.
  2. There shall be exactly one ontology (L0.Ontology) defined in each ontology bundle.
  3. The Bundle-Name of an ontology shall be the unversioned URI of the ontology without the '-0.0' suffix e.g. http://www.simantics.org/Simulation
  4. The first two digits of the Bundle-Version of an ontology shall be the ontology version as specified in the ontology URI e.g. '1.2'
  5. The Bundle-SymbolicName (bundle id) of a working ontology is unchanged when versions grow (e.g. org.simantics.simulation.ontology)
  6. The Bundle-SymbolicName (bundle id) of a frozen ontology is a version-dependent derivative of the id from the working ontology (e.g. org.simantics.simulation.ontology-1.1)

Model Migration

A project in a database contains models of different versions created with different versions of software features.

The database can host multiple versions of ontologies which enables old models to exist and to be imported in the database. A typical software feature can only manipulate models defined with the latest versions of some ontologies.

Software features can make model migration from models created with previous versions of the software. Each model is associated in the database with a single software feature version, which then can be used to determine the actions needed for migrating models to the latest ontological definitions. The version modelling is defined in org.simantics.softwareconfiguration.ontology.

The user can browse the old and new models contained in the database and perform model migration at will.

Making software releases

A released Simantics feature uses a set of ontologies with specified version numbers. All models associated with a specific software version need access to these ontology versions even after the ontologies have evolved. Thus it is necessary to release and freeze all versions of used ontologies whenever a software is released. Thus the procedure for making a software release includes

The release process

  • Before the build
    1. Make usual tagging and branching of all released plugins in Subversion
  • Right after the build
    1. For all working ontologies which do not correspond to a frozen version : freeze ontology plugin and store as a tag
    2. Increment the software version number of models
  • During modelling when ontology is first modified (before this the working ontology was exactly some frozen ontology)
    1. Increment ontology version number. (Include the corresponding frozen ontology into product dependencies to enable migration).