.. _versioning_sunflower: ==================== Versioning Sunflower ==================== .. admonition:: 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. .. uml:: @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 ------------------- 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`_. .. _Semantic Versioning: http://semver.org/ .. _Maven version numbering strategy: https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN400 --------------------------- Versioning Sunflower Native --------------------------- .. uml:: @startuml package "Sunflower Native" as PKG_NATIVE { component "XSB and Flora" as XSB_FLORA component "Flserver" as FLSERV } @enduml XSB and Flora ============= 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. 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. ------------------------------- 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. .. uml:: @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: .. code-block:: bash . ├── 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. 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 ```` element in the corresponding ``.pom`` file: .. code-block:: bash . ├── 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. --------------------------- 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. .. uml:: :width: 600px @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: MANIFEST.MF ----------- .. code-block:: txt :linenos: :emphasize-lines: 5 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 ```` element for both this POM and the parent POM, if defined: .. code-block:: xml :linenos: :emphasize-lines: 9, 14 4.0.0 com.sri.sunflower com.sri.sunflower 1.0.1-SNAPSHOT ../ com.sri.sunflower com.sri.sunflower.console 1.0.1-SNAPSHOT eclipse-plugin SRI EULA http://sunflower.csl.sri.com/index.php/legal/eula/ .. 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. .. code-block:: txt . ├── 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