--- /dev/null
+This document addresses the issue of how simantics application migrates from one version to the next. The scope includes software and ontology development.\r
+\r
+## Ontology Migration\r
+An ontology is a compilation of shared *concepts* (=types, relations and instances).\r
+\r
+ http://www.simantics.org/Layer0-1.0\r
+ http://www.simantics.org/Layer0-1.0/ConsistOf\r
+ http://www.simantics.org/Layer0-1.0/Library\r
+\r
+Ontologies are versioned according to the following scheme\r
+\r
+ <Ontology URI>-<major version>.<minor version>\r
+\r
+For example\r
+\r
+ http://www.simantics.org/Layer0-1.0\r
+\r
+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\r
+\r
+* **versioned URI** as the proper URI of the resource e.g. `http://www.simantics.org/Layer0-1.0/ConsistsOf`\r
+* **unversioned URI** where version information is omitted e.g. `http://www.simantics.org/Layer0-0.0/ConsistsOf`\r
+\r
+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**.\r
+\r
+Additionally we define\r
+\r
+* **working ontology** as an ontology bundle which contains the **latest** version of the ontology e.g. *org.simantics.simulation.ontology*\r
+* **released ontology** as an ontology bundle which is frozen, renamed and never again changed e.g. *org.simantics.simulation.ontology-1.1*\r
+\r
+The following simple rules for ontology development are defined to enable version migration\r
+\r
+### Modelling rules\r
+\r
+1. All ontology versions shall be completely self-contained. All concepts are declared in all versions of an ontology.\r
+2. There shall be exactly one ontology (L0.Ontology) defined in each ontology bundle.\r
+3. 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>\r
+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'\r
+5. The **Bundle-SymbolicName** (bundle id) of a working ontology is unchanged when versions grow (e.g. org.simantics.simulation.ontology)\r
+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)\r
+\r
+## Model Migration\r
+\r
+A project in a database contains models of different versions created with different versions of software features.\r
+\r
+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.\r
+\r
+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**.\r
+\r
+The user can browse the old and new models contained in the database and perform model migration at will.\r
+\r
+## Making software releases\r
+\r
+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\r
+\r
+### The release process\r
+\r
+* **Before the build**\r
+ 1. Make usual tagging and branching of all released plugins in Subversion\r
+* **Right after the build**\r
+ 1. For all working ontologies which do not correspond to a frozen version : freeze ontology plugin and store as a tag\r
+ 2. Increment the software version number of models\r
+* **During modelling when ontology is first modified** (before this the working ontology was exactly some frozen ontology)\r
+ 1. Increment ontology version number. (Include the corresponding frozen ontology into product dependencies to enable migration).\r
Code Review / simantics / platform.git / blobdiff