Dependency upgrades | Eclipse ESCET™ development documentation

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:
- Check the Simultaneous Release overview page for the link between platform version (e.g. 4.20) and release name (e.g. 2021-06).
- Check https://www.eclipse.org/projects/project-plan.php?planurl=https://www.eclipse.org/eclipse/development/plans/eclipse_project_plan_N_NN.xml with N_NN replaced by the platform version (e.g. 4_20), for the project plan of the release, including detailed information about the supported target environments (operating systems, Java versions, etc).
- Check https://www.eclipse.org/eclipse/development/readme_eclipse_N.NN.php with N.NN replaced by the platform version (e.g. 4.20), for the README of the release.
- Check the New & Noteworthy page for the new release and all intermediate releases since the previous version. Note that you can switch to the New & Noteworthy pages of previous releases using the dropdown at the bottom of the page.
Upgrade the development environment
- Alternative 1: set up a fresh new development environment.
  - The benefit of this alternative is that you get a clean new environment, and can use it side-by-side with existing development environments. The downside is that you have to manually configure the new environment, or manually migrate your workspace and settings. You also have to cleanup or remove your old development environments, in case you don’t use them anymore.
  - Set up a new development environment for the new Eclipse IDE version.
- Alternative 2: in-place upgrade of an existing development environment.
  - The benefit of this alternative is that you can keep your existing environment, preventing multiple such environments as well as manual migrations. The downside is that you run the risk of older things remaining in your development environment, requiring manual cleanup.
  - Update the P2 Director section of the Oomph setup (org.eclipse.escet.setup), if needed. Especially, consider what is no longer compatible with the new Eclipse version and remove it, or replace it by an alternative.
  - If you removed anything from the P2 Director section of the Oomph setup, also remove it manually from your development environment:
    
    Click Help About Eclipse Platform.
    
    Click the Installation Details button.
    
    Select on the Installed Software tab the item to remove and click the Uninstall… button.
    
    On the Uninstall dialog, click the Finish button.
    
    When asked to restart the Eclipse Platform, click Restart Now (newer Eclipse versions) or Yes (older Eclipse versions).
    
    Repeat these steps for each item that was removed from the P2 Director section of the Oomph setup.
  - Update your installation profile for the new Eclipse version, and apply it:
    
    From the toolbar, select the dropdown menu of the Open User item and choose Open Installation.
    
    Select the Installation file:… node.
    
    In the Properties view, change the Product Version to the Eclipse Platform edition of the new Eclipse version.
    
    Save the installation.setup file.
    
    Click File Restart.
    
    Once Eclipse restarts, you should see some initialization progress at the bottom right corner of the development environment window.
    
    Wait for the Eclipse Update dialog to appear, indicating that The installation does not satisfy the requirements list below.
    
    Click the Install button to update Eclipse.
    
    Wait for the update to complete, while observing the progress at the bottom right corner of the development environment window.
    
    If a Trust dialog appears, click Select All and then Trust Selected.
    
    After some time, notice the Oomph icon with the flashing warning sign () at the bottom right corner of the development environment window.
    
    Click it to open the Eclipse Updater window.
    
    Click Finish to restart Eclipse, completing the update.
    
    Once Eclipse restarts, you may see a Older Workspace Version popup.
    
    If so, click Continue to update your workspace to the new Eclipse version.
Version updates
- Update the target platform (org.eclipse.escet.releng.target/org.eclipse.escet.releng.target.target), configuring new versions for the Eclipse IDE and Orbit update sites.
- Update dev-env-setup.asciidoc to match the 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 the product (org.eclipse.escet.product/escet.product).
- Update Maven plugin third party dependency versions to match the versions of these plugins from the target platform (org.eclipse.escet.common.asciidoc/pom.xml).
- Commit any changes.
Update target platform and adapt to the new Eclipse version
- Let Oomph reactivate the target platform, and address any issues.
- Commit any changes.
- Force a rebuild in Eclipse (Project Clean…).
- Check the workspace for any errors/warnings and address them if any.
- Commit any changes.
- Check New and Noteworthy (release notes) of the new Eclipse version and relevant intermediate versions for changes and adapt as necessary.
- Commit any changes.
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.
- Manually update the org.eclipse.escet.*.metamodel projects to have similar error/warnings settings as the rest of the projects (be aware, some settings are configured differently).
- Force a rebuild in Eclipse (Project Clean…) and check for any warnings/errors, addressing them if any.
Eclipse application launch configurations
- Select each Eclipse application launch configuration in the Run Configurations dialog, then select the next one, and so on. In the Run Configurations dialog, these launch configurations are under the Eclipse Applications category.
- Run each Eclipse application launch configuration, from the Run Configurations dialog. Make sure they work as expected.
- If Eclipse makes any changes to the corresponding *.launch files for these launch configurations, commit the changes.
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 version of the maven-plugin-api to match new Maven version (org.eclipse.escet.common.asciidoc/pom.xml).
- Update version of the maven-plugin-annotations if needed (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.
Perform a license check (misc/license-check-dependencies/license-check-dependencies.sh).
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 update site URL in the target platform (org.eclipse.escet.releng.target/org.eclipse.escet.releng.target.target).
- Re-activate the target platform 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.