Dependency upgrades

The Eclipse ESCET toolset has various dependencies. From time to time, these dependencies need to be upgraded. This page discusses for some of the major dependencies when to upgrade and how to upgrade:

Eclipse Platform/IDE upgrades

The Eclipse ESCET IDE is based on the Eclipse IDE, which in turn is based on the Eclipse Platform. The Eclipse IDE is also used as the development environment of choice for Eclipse ESCET development.

The Eclipse ESCET upgrade policy for the Eclipse Platform/IDE is:

  • Considering the overhead, only upgrade if there is a use for it. For instance, if we need a bug fix, some new feature, or so.

  • Upgrade to a new Eclipse version at least once a year, to stay current.

  • Consider the interplay between Eclipse and Java versions. Upgrading Eclipse may require upgrading Java if the new Eclipse version has a higher minimum Java version requirement. Upgrading Java may require upgrading Eclipse to a newer version that supports that Java version.

To upgrade to a new Eclipse Platform/IDE version:

  • Check out the information for the new version:

  • New development environment

  • Version updates

    • Look up Orbit version for the new Eclipse Platform/IDE release, see https://download.eclipse.org/tools/orbit/downloads/.

    • Update Oomph setup (org.eclipse.escet.setup), configuring new Eclipse IDE and Orbit versions.

    • Update dev-env-setup.asciidoc to match new Eclipse version.

    • Update org.eclipse.platform version for the product feature (org.eclipse.escet.product.feature/feature.xml).

    • Update Eclipse and Orbit update site URLs in product (org.eclipse.escet.product/escet.product).

    • Update Eclipse and Orbit update site URLs in update site (org.eclipse.escet.product/category.xml).

    • Update Maven plugin third party dependency versions to match Orbit versions (org.eclipse.escet.common.asciidoc/pom.xml).

  • Update target platform and address any issues

    • Let Oomph regenerate the target platform, and commit any changes.

    • Force a rebuild in Eclipse (Project  Clean…​).

    • Check workspace for any errors/warnings and address them if any.

    • Check New and Noteworthy (release notes) of the new Eclipse version and relevant intermediate versions for changes and adapt as necessary.

  • Java formatter profile

    • Right click the org.eclipse.escet.common.java project in the Package Explorer view and choose Properties.

    • In the properties dialog, select Java Code Style  Formatter.

    • Make sure the Unmanaged profile is selected and click Edit…​.

    • Change the Profile name to tmp.

    • Click OK to close the profile editing dialog, and then clicking Apply and Close to close the properties dialog.

    • Remove the tmp profile:

      • Remove the formatter_profile=_tmp line from the .settings/org.eclipse.jdt.ui.prefs file in the project.

      • Navigate to Window  Preferences.

      • In the dialog, navigate to Java  Code Style  Formatter.

      • Select the tmp profile.

      • Click the Remove button and confirm the removal by clicking Yes.

      • Close the preference dialog by clicking Apply and Close.

      • If an Oomph preference recorder dialog appears, dismiss it by clicking Cancel.

    • If in the org.eclipse.escet.common.java project, in the .settings directory, there are changes to any of the *.prefs files:

      • Run ./copy_here.bash ../../common/org.eclipse.escet.common.java from misc/java-code-style to copy the new preferences to the central place.

      • Run ./copy_there.bash from misc/java-code-style to copy the new preferences to all relevant projects.

      • Refresh all projects, and wait until the rebuild completes.

      • Commit the preference changes.

      • Reformat all projects.

      • Commit any code changes.

    • In case of new formatter preferences, configure them as desired. Apply each preference change separately, to allow easier reviewing:

      • Change a single formatter preference on the org.eclipse.escet.common.java project. This requires giving the unmanaged profile the name tmp again, as before.

      • Remove the tmp profile, as before.

      • Run ./copy_here.bash ../../common/org.eclipse.escet.common.java from misc/java-code-style to copy the changed formatter preference to the central place.

      • Run ./copy_there.bash from misc/java-code-style to copy the changed formatter preference to all relevant projects.

      • Refresh all projects, and wait until the rebuild completes.

      • Commit the preference changes.

      • Reformat all projects.

      • Commit reformatting changes.

    • If any changes were made to the formatter preferences, manually update the org.eclipse.escet.*.metamodel projects to have the same formatter settings as the rest of the projects.

  • Java errors/warnings settings

    • Right click the org.eclipse.escet.common.java project in the Package Explorer view and choose Properties.

    • In the properties dialog, select Java Compiler  Errors/Warnings.

    • Make a dummy change and apply it by clicking Apply and Close.

    • Click Yes when asked to Rebuild the project now to apply the changes of the Error/Warning settings?.

    • Revert the dummy change, using again the same steps.

    • In case of changes to *.prefs files in the .settings directory of that project, configure the new preferences as desired.

    • Run ./copy_here.bash ../../common/org.eclipse.escet.common.java from misc/java-code-style to copy the new preferences to the central place.

    • Run ./copy_there.bash from misc/java-code-style to copy the new preferences to all relevant projects.

    • Force a rebuild in Eclipse (Project  Clean…​) and check for any warnings/errors, addressing them if any.

  • Update Maven version

    • Check the embedded Maven version, by navigating to Run  Run Configurations…​, selecting the build launch configuration under Maven Build, and observing the Maven Runtime version.

    • Ensure the Maven version in Jenkinsfile matches the embedded Maven version.

    • Ensure the Maven version in misc/license-check-dependencies/Jenkinsfile matches the embedded Maven version.

    • Update versions of Maven plugins (maven-plugin-*) to match new Maven version (org.eclipse.escet.common.asciidoc/pom.xml).

    • Update version of the maven-plugin-plugin if needed (org.eclipse.escet.releng.configuration/pom.xml).

  • Validation

    • Run a Maven build.

    • Ensure no errors or warnings during Maven build.

  • Dependency information

    • Run misc/license-check-dependencies/license-check-dependencies.sh and update DEPENDENCIES.txt according to the output.

    • Run misc/license-check-dependencies/license-check-dependencies.sh again, to ensure DEPENDENCIES.txt is up-to-date.

Tycho upgrades

Eclipse Tycho is used for the Eclipse ESCET build.

The Eclipse ESCET upgrade policy for Tycho is:

  • Typically upgrading to a newer version can be done at any time, if it is considered relevant.

To upgrade to a new Tycho version:

  • Update version in org.eclipse.escet.root/.mvn/extensions.xml.

  • Update tycho.version in org.eclipse.escet.releng.configuration/pom.xml.

  • Update maven.minimal.version in org.eclipse.escet.releng.configuration/pom.xml, if the new Tycho version requires a higher Maven version.

  • Check Tycho release notes for changes and adapt as necessary.

  • Run a Maven build.

  • Ensure no errors or warnings during Maven build.

Java upgrades

Most of the Eclipse ESCET source code is written in Java.

The Eclipse ESCET upgrade policy for Java is:

  • Considering the overhead, only upgrade if there is a use for it. For instance, if we need a bug fix, some new feature, or so.

  • Upgrade when a Java version we use is no longer actively supported.

  • Only upgrade to a Java LTS release.

  • Don’t upgrade to newer Java versions immediately, but only after (industrial) adoption is high enough. As a general guideline, if at least 50% of developers, users and enterprises use the new LTS version, consider upgrading. Java usage is regularly surveyed, and reports can typically be found online. For instance, the 2021 Jakarta EE Developer Survey Report of the Eclipse Jakarta EE project indicates that in 2021 about 58% of the developers and 11% of the enterprises used Java 11.

  • Consider the interplay between Java and Eclipse versions. Upgrading Java may require upgrading Eclipse to a newer version that supports that Java version. Upgrading Eclipse may require upgrading Java if the new Eclipse version has a higher minimum Java version requirement.

To upgrade to a new Java version:

  • For major Java versions (e.g. 17 to 18):

    • Update all (plugin) projects:

      • Update Bundle-RequiredExecutionEnvironment for all plug-in manifests.

      • Update JRE_CONTAINER in all .classpath files.

      • Update JRE_CONTAINER in all launch configurations (.launch files).

      • Update Java versions in all org.eclipse.jdt.core.prefs files (compiler.codegen.targetPlatform, compiler.compliance, and compiler.source).

    • Update all metamodel projects (org.eclipse.escet.*.metamodel projects):

      • Update the autofix.py scripts of these projects, by changing the compliance level resulting from replacements.

      • Change in all *.genmodel files the complianceLevel.

      • Regenerate the model code for each metamodel project, by opening the corresponding .genmodel file, right clicking the root node of the opened generator model, and choosing Generate Model Code. There won’t always be changes.

    • Update the product:

      • Update osgi.requiredJavaVersion in the product (org.eclipse.escet.product/escet.product).

      • Update osgi.requiredJavaVersion in the product launch configuration (org.eclipse.escet.product/*.launch).

    • Update the build:

      • Update Java version for escet.java.version in org.eclipse.escet.releng.configuration/pom.xml.

      • Update Java version for executionEnvironment in org.eclipse.escet.releng.configuration/pom.xml.

      • Update Java version in Jenkinsfile.

      • Update Java version in misc/license-check-dependencies/Jenkinsfile.

    • Update all Java code and documentation:

      • Update Java keywords for org.eclipse.escet.common.java.JavaCodeUtils.JAVA_IDS. Update the keywords themselves and the field’s JavaDoc, including the link to the Java Language Specification (JLS).

      • Update dev-env-setup.asciidoc to match new Java version.

      • Update links to specific versions of the Java documentation (search for https://docs.oracle.com).

    • Search for the current Java version to find other references (e.g., search for 17).

  • For any Java versions (e.g. 17 to 18, or 17.0.1 to 17.0.2):

    • Update the JustJ version (eclipse.justj.version.* variables) in the Oomph setup (org.eclipse.escet.setup).

    • Regenerate the target platform file using Oomph.

    • Update JustJ version for the product feature (org.eclipse.escet.product.feature/feature.xml).

    • Force a rebuild in Eclipse (Project  Clean…​) and check for any warnings/errors, addressing them if any.

    • Run a Maven build.

    • Ensure no errors or warnings during Maven build.

    • Run misc/license-check-dependencies/license-check-dependencies.sh and update DEPENDENCIES.txt according to the output.

    • Run misc/license-check-dependencies/license-check-dependencies.sh to ensure DEPENDENCIES.txt is up-to-date.