X-Git-Url: https://gerrit.simantics.org/r/gitweb?p=simantics%2Fplatform.git;a=blobdiff_plain;f=docs%2FDeveloper%2FOntology%2FVersionMigration.md;fp=docs%2FDeveloper%2FOntology%2FVersionMigration.md;h=383c31ce9d22d7de66d7882d4e3818c50bee3a55;hp=0000000000000000000000000000000000000000;hb=a9ec58f08ccc02e65b1cab6aedff25e0cf3c6444;hpb=5998374f7e179cfaf451c220216adc18c823047f diff --git a/docs/Developer/Ontology/VersionMigration.md b/docs/Developer/Ontology/VersionMigration.md new file mode 100644 index 000000000..383c31ce9 --- /dev/null +++ b/docs/Developer/Ontology/VersionMigration.md @@ -0,0 +1,63 @@ +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 + + -. + +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).