platform/jewel/docs/upgrade-compose.md
The upgrade process primarily involves updating artefact version numbers, and potentially adding new dependency entries, across multiple build configuration files. There are three build systems that are impacted by an update:
Most of the changes can be performed in the community repository; however, some are only possible in the monorepo and must be performed by someone at JetBrains with the necessary access.
Keep in mind that major Compose upgrades may require a lot of time to get right.
The major steps in the upgrade that can be:
Determine the specific Compose version you intend to upgrade to. We try to use CMP versions with stability of beta or better, only using alphas if we have a specific need and our timelines don't allow us to wait for a beta.
The list of CMP releases is here: https://github.com/JetBrains/compose-multiplatform/releases
Update the libs.versions.toml version catalog with the new Compose version.
That should cover the Gradle build update. Make sure the Gradle build still works correctly, e.g., by running the
build task.
The JPS build is updated from within IntelliJ IDEA. You can do these changes manually in the iml files, but it is
extremely unpractical.
Open the intellij-community project in IntelliJ IDEA
Open the Project Structure dialog
Navigate to Modules > intellij.libraries.compose.foundation.desktop module
Double-click the compose.foundation.desktop library
Click the Edit button, pick the new version and follow the instructions. Make sure the sources and Javadoc options are selected, and leave the rest to the defaults.
Note down the Skiko version used by the CMP dependency. You can do that from here, or by clicking the link next to the Transitive dependencies checkbox and searching for skiko in the dialog that shows up.
[!IMPORTANT] Do not make any changes in the Transitive dependencies dialog — click Cancel when you've found the Skiko version to use.
Navigate to the intellij.libraries.compose.foundation.desktop.junit module and update the org.jetbrains.compose.ui.ui.test.junit4.desktop library to the same version
Navigate to the intellij.libraries.compose.runtime.desktop module and update the various libraries the same way as you did in compose-foundation-desktop
Navigate to the intellij.platform.jewel.ui module
Update the org.jetbrains.compose.components.components.resources and org.jetbrains.compose.components.components.resources.desktop dependencies to the same CMP version with the same procedure as above
Now it's time to update the Skiko dependency. Go to the intellij.libraries.skiko module
If the Skiko version currently listed is different from the one CMP requires — which is usually the case — then follow the same procedure as above to upgrade Skiko to the required version. Note that the required Skiko version may not be the latest one.
skiko-awt-runtime-all is a custom-built package hosted in the
IntelliJ Dependencies
repo. If the required version is not available, you'll need to ask Kuba/Nebojsa to build it and publish it.You should now be able to see the changes in .iml files that correspond to the upgrades. If they do not immediately
show up, you can use the Save all action to force the IDE to write changes to disk.
The Bazel build is generated from the JPS one; updating this is just a matter of running the
jpsModelToBazelCommunityOnly.cmd script. The script will update a
number of BUILD.bazel and MODULE.bazel files.
Double-check manually that the script only makes changes that match the JPS changes. Revert any spurious change there may be. Double-check against IJP changes if you spot something suspicious — it may have slipped in to JPS as well.
It may not be required, but it could be a good idea to regenerate the icon classes by running the Generate icon classes (ex icons.gant) run configuration. It probably will not result in any changes — but if it does, those changes must be thoroughly inspected before committing.
After you're done with the steps above, it's time to verify that the upgrade was successful. To do so, you can run the
GitHub CI checks locally (see jewel-checks.yml), and then thoroughly
smoke test the standalone and IDE samples. If you find any regression, notify the team immediately.
You should also run all the IJP tests using the tests.cmd script in the community repo root.
There are a few steps in the process that can only be performed by JetBrains employees in the monorepo:
build/expected/ultimate-content-platform.yaml file defines the expected
content of the ultimate platform. This may beed to be updated