JUnit5 Update Process

The following is a guide through the process of updating the JUnit 5 stack in Orbit, based off of https://bugs.eclipse.org/bugs/show_bug.cgi?id=567358#c2 . This guide assumes a locally cloned git repository of orbit-recipes and some basic understanding of the Maven build system and OSGi metadata.

• For most JUnit 5 minor version bumps, the change almost entirely involves a simple search and replace. For example, for the update from 5.5.1 to 5.6.0, the following needed to be done :

cd junit/junit5
find . -type f | xargs sed -i 's/5.5.1/5.6.0/g'
find . -type f | xargs sed -i 's/1.5.1/1.6.0/g'
for m in `ls -1 | grep 1.5.1`; do git mv $m ${m/1.5.1/1.6.0/} ; done;
for m in `ls -1 | grep 5.5.1`; do git mv $m ${m/5.5.1/5.6.0/} ; done;

• The JUnit 5 bundles in releng/aggregationfeature/feature.xml (from the root of the project) must also be updated.

org.apiguardian, and org.opentest4j did not need to be updated but the org.junit dependence went from 4.12 to 4.13. So, how was it known this was required ?

• Discover dependency changes by running the script from below

In this example we use JUnit 5.6.0 -> 5.7.0 as this is the script needed to be run more recently. As modules are added/removed, the script can evolve accordingly. (Ideal to run in an empty directory)

for art in junit-platform-{commons,engine,launcher,runner,suite-api}; do
  for v in "1.6.0" "1.7.0"; do
    curl -L -s -O https://search.maven.org/remotecontent?filepath=org/junit/platform/${art}/${v}/${art}-${v}.pom
  done
  diff -u ${art}*
done

art=junit-vintage-engine
for v in "5.6.0" "5.7.0"; do
  curl -L -s -O https://search.maven.org/remotecontent?filepath=org/junit/vintage/${art}/${v}/${art}-${v}.pom
done
diff -u ${art}*

for art in junit-jupiter-{api,engine,migrationsupport,params}; do
  for v in "5.6.0" "5.7.0"; do
    curl -L -s -O https://search.maven.org/remotecontent?filepath=org/junit/jupiter/${art}/${v}/${art}-${v}.pom
  done
  diff -u ${art}*
done

This compares the pom files of the old and new artifacts and is a good way to determine what may have changed. Changes may need to be reflected in the corresponding bundle's osgi.bnd file.

There may be a few false positives, like pom dependencies being modified around, but generally, you're looking for version numbers of dependency artifacts that are changed/added/removed . Obviously ignore the version numbers of the poms themselves (eg. 5.5.1 -> 5.6.0).

• The final step is to update the CQs for the bundles, although usually this would have been filed beforehand. CQ 21545 is an example of how the CQ should appear.

Once a change gets pushed for review, (and CQs get updated acccordingly in ip_log.xml), gerrit-orbit-recipes should trigger a build and response on the review with a temporary generated p2 repository that can be used to verify things work as expected. After the change is merged it should be available as an I-build shortly or until a milestone release.

Update JUnit 5 in JDT

After the new JUnit bundles have been added in Orbit, download them and replace the old bundles in Eclipse SDK with the new ones by placing them in the dropins/plugins folder of the SDK. Launch Eclipse and verify that the new bundles are being used and you are able to run JUnit tests in a variety of scenarios e.g. in a modular / non-modular project, with or without using test folders, etc. Also, go through the JUnit release notes to see any API additions or deprecations/removals which need to be adapted into the JDT code. Check that no new warnings are added in the JDT code. Support for new features in JDT can be added later after switching the JUnit version. Once the things look good, update the eclipse.platform.releng.prereqs.sdk/eclipse-sdk-prereqs.target file with new bundle versions and point to the latest Orbit repo location e.g. here. Verify everything in the next I-build and add an N&N entry.