1.7. Versioning Sunflower

WORK IN PROGRESS

This section is subject to change as it is under contruction.

The Sunflower family of projects is structured into many packages which are independently versioned. Usually all artifacts within a specific package utilize the same version number. Below is a high level project overview.

@startuml
package "Sunflower Foundation" as PKG_FDN {
  component "Floralib" as FDN
}

package "Sunflower Foundation Tasks" as PKG_FDN_TASKS {
  component "SunflowerTasks" as FDN_TASKS
}

package "Sunflower Native" as PKG_NATIVE {
  component "XSB and Flora" as XSB_FLORA
  component "Flserver" as FLSERV
}
package "Sunflower Documentation" as PKG_DOCS {
  component "Sunflower User Manual" as DOCS
  component "Sunflower Developer Documentation" as DEV_DOCS
  component "Flora Tutorial" as TUTORIAL
  DOCS -u-> DEV_DOCS : includes
  DOCS -d-> TUTORIAL : includes
}
PKG_DOCS --> FDN : depends

package "Sunflower Studio IDE" as PKG_IDE {
  component "Floralib Bundle" as FB
  component "Sunflower Studio CE" as CE
  component "Sunflower Studio Tasks" as TASKS
  FB -l-> FDN : depends
  CE -l-> PKG_DOCS : requires
  CE --> XSB_FLORA : requires
  CE -u-> FB : depends
  CE <-d- TASKS : depends
  TASKS -l-> PKG_DOCS : requires
  TASKS --> XSB_FLORA : requires
  TASKS -r-> FDN_TASKS : depends
}
@enduml

1.7.1. Versioning Strategy

The current strategy for versioning Sunflower is fairly loose and should likely be standardized. Currently all products utilize snapshot builds, with the major, minor, and incremental version numbers not incrementing according to any logical way, unless specified otherwise.

We are considering transitioning to Semantic Versioning where given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards-compatible manner, and
  3. PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

This process should be complimentary to the Maven version numbering strategy.

1.7.2. Versioning Sunflower Native

@startuml
package "Sunflower Native" as PKG_NATIVE {
  component "XSB and Flora" as XSB_FLORA
  component "Flserver" as FLSERV
}
@enduml

1.7.2.1. XSB and Flora

1.7.2.1.1. Version Number Strategy

XSB and Flora-2 are open source products that do have their own release cycle. However neither project provides pre-built binaries. Additionally the Sunflower program has contributed funds to fix bugs that impact Sunflower products, and we are often using an intra-release version of the products.

As both projects currently utilize Subversion for version control, we have chosen to utilize the Subversion revision number as the means to track XSB and Flora-2 binary artifacts.

Major Minor Incremental
0 0 SVN revision

Warning

This strategy may be updated as Flora-2 project has discussed changing SCM solutions that would not provide an serial value for use as an incremental value.

1.7.2.1.2. Updating Version Number

For details on updating the version of XSB and Flora, see the README files located within each directory of the sunflower-native source repository.

The general procedure for updating XSB and Flora binaries are as follows.

  1. Update the version numbers for the native binary artifacts.
    • SEE sunflower-native/scripts/README.rst
  2. Update and deploy the source artififacts.
    • SEE sunflower-native/dep-source/README.rst
  3. Build the native binary artifacts and validate that the patch files still work.
    • SEE sunflower-native/sunflower-native/README.rst
    • SEE sunflower-native/sunflower-native-build/jenkins-build-all-platforms-cpp.sh
  4. Once binaries are validated to function. Commit updated POM files to SCM. Continuious Integration will rebuild and deploy these artifacts to Artifactory.

At this point you can update the dependencies in other projects that utilize the XSB and Flora artifacts generated.

1.7.3. Versioning Sunflower Foundation

Sunflower Foundation is composed of 3 separate components:

  • floralib: SRI developed Java library for interfacing with XSB Engine to run Flora.
  • floralib-ext: Third-party Java libraries required by floralib.
  • floralib-thalamus: Third-party Java libraries used by floralib that are missing source, build instructions, and or not available via a public or private binary repository.

Two addtional components, floralib-obfuscated and floralib-ext-obfuscated produce obfuscated variants of their dependencies for use in commercial solutions. The version numbers of these two component modules should mirror floralib and floralib-ext respectively.

@startuml
package "Sunflower Foundation" as PKG_FDN {
  component "floralib" as FDN
  component "floralib-ext" as FDNEXT
  component "floralib-thalamus" as THALAMUS
  FDN --> FDNEXT
  FDN --> THALAMUS
}

package "Sunflower Foundation Obfuscated" as PKG_OBF {
  component "floralib-ext-obfuscated" as FDNEXTOBF
  component "floralib-obfuscated" as FDNOBF
  FDNEXTOBF --> FDN
  FDNOBF --> FDNEXT
}
@enduml

As floralib, floralib-ext, floralib-obfuscated, and floralib-ext-obfuscated artifacts are versioned together. Updating the version number, involves incrementing the values within the Maven POM files of the following modules:

.
├── floralib
│   └── pom.xml
├── floralib-ext
│   └── pom.xml
└── sf-foundation-obfuscate
    ├── floralib-ext-obfuscated
    │   └── pom.xml
    ├── floralib-obfuscated
    │   └── pom.xml
    └── pom.xml

Once updated the next Maven build will produce newly versioned artifacts.

1.7.3.1. Versioning floralib-thalamus

The floralib-thalamus component is versioned differently than the rest of the component modules, as these projects are currently not built as part of the pipeline and are kept in binary form. Updating the version for each artifact involves replacing the associated library file, and updating the <verson> element in the corresponding .pom file:

.
├── floralib-thalamus
    ├── geo
    │   └── geo-1.0.pom
    ├── interprolog
    │   └── interprolog-2.1.x.pom
    └── srm
        └── srm-1.0.pom

Executing the install goal will install the updated artifact within your local maven repository. Executing the deploy goal will install the updated artifacts in the remote artifactory.

1.7.4. Versioning Sunflower Studio

While Sunflower Studio is divided into multiple bundles and modules, all modules except for de.ralfebert.rcputils utilize the same version number.

de.ralfebert.rcputils is an abandoned Eclipse RCP plugin which is used in a few places for handling some complex tabular UI within Sunflower Studio. The version for this component should stay fixed at it’s last released version.

@startuml
    package "Floralib Bundle" as FB {
        [sfplist]
        [com.sri.floralib]
        [logging] --> [logging.config]
    }

    package "Sunflower Studio CE" as CE {
        top to bottom direction
        [core] --> [de.ralfebert.rcputils]
        [core] --> [console]
        [core] --> [importer]
        [core] --> [main]
        [core] --> [navigator]
        [core] --> [ontologyeditor]
        [core] --> [query]
        [core] --> [reasoner]
        [core] --> [texteditor]
        [core] --> [uilib]
        [core] --> [license]
        [core] --> [p2.core]
        [core] --> [distrib.core]
    }

    package "Sunflower Studio Tasks" as TASKS {
        [tasks] --> [fxquery]
        [tasks] --> [p2.tasks]
        [tasks] --> [distrib.tasks]
    }

    CE -u-> FB : includes
    TASKS -u-> CE : includes

@enduml

As mentioned the rest of the project should be versioned using the same version number, as all modules are always built in the same build lifecycle.

When versioning the Sunflower Studio modules, each module is and Eclipse RCP plugin or application, and hence, extra care is needed when updating the version number.

In the MANIFEST.MF file, you will need to update the Bundle-Version with the new version number:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Sunflower Console Plug-in
Bundle-SymbolicName: com.sri.sunflower.console;singleton:=true
Bundle-Version: 1.0.1.qualifier
Bundle-Activator: com.sri.sunflower.console.FloraConsolePlugin
Bundle-Localization: plugin
Require-Bundle: org.eclipse.core.runtime,
 org.eclipse.ui,
 org.eclipse.ui.console;visibility:=reexport
Eclipse-LazyStart: true
Export-Package: com.sri.sunflower.console,
 com.sri.sunflower.console.preference
Bundle-Vendor: SRI International
Bundle-RequiredExecutionEnvironment: JavaSE-1.8

And in the pom.xml file, you will need to update <version> element for both this POM and the parent POM, if defined:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright (C) 2014 SRI International, Menlo Park, USA -->
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>com.sri.sunflower</groupId>
    <artifactId>com.sri.sunflower</artifactId>
    <version>1.0.1-SNAPSHOT</version>
    <relativePath>../</relativePath>
  </parent>
  <groupId>com.sri.sunflower</groupId>
  <artifactId>com.sri.sunflower.console</artifactId>
  <version>1.0.1-SNAPSHOT</version>
  <packaging>eclipse-plugin</packaging>
  <licenses>
    <license>
            <name>SRI EULA</name>
            <url>http://sunflower.csl.sri.com/index.php/legal/eula/</url>
    </license>
  </licenses>
</project>

Note

When building SNAPSHOT versioned builds, The version number in a POM file should end with -SNAPSHOT and in MANIFEST.MF files the number should end in .qualifier. This string value will be replaced with the current build identifier during the build.

Here is the list of all current MANIFEST and POM files within the project. Note that that all version numbers execept for those in the sunflower-thirdparty should match.

.
├── sunflower-bootstrap
│   └── pom.xml
├── sunflower-open
│   ├── com.sri.floralib
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.product.floralib
│   │   └── pom.xml
│   ├── com.sri.sunflower.console
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.distrib.core
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.importer
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.license
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.logging
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.logging.config
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.main
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.navigator
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.ontologyeditor
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.p2.core
│   │   └── pom.xml
│   ├── com.sri.sunflower.product.core
│   │   └── pom.xml
│   ├── com.sri.sunflower.query
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.reasoner
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.texteditor
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.uilib
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── pom.xml
│   └── sfplist
│       └── pom.xml
├── sunflower-sri
│   ├── com.sri.bundledependency
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.product.tasks
│   │   └── pom.xml
│   ├── com.sri.rave.flora.task
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.dependencyeditor
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.distrib.tasks
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.fxquery
│   │   ├── META-INF
│   │   │   └── MANIFEST.MF
│   │   └── pom.xml
│   ├── com.sri.sunflower.p2.tasks
│   │   └── pom.xml
│   └── com.sri.sunflower.product.tasks
│       └── pom.xml
└── sunflower-thirdparty
    └── de.ralfebert.rcputils
        ├── META-INF
        │   └── MANIFEST.MF
        └── pom.xml