Skip to content

Platform Migration Guide

This guide walks you through migrating all MPS platforms starting from uploading the new JBR and ending at migrating IETS3 ⧉. MPS_VERSION stands for the MPS version such as 2022.3. Before starting the migration process, read Migration Guide | MPS Documentation ⧉ first. Before starting a migration for a platform, make sure that all commits have landed on master by merging the maintenance branches into each other starting from the oldest version. The last maintenance branch should then be merged into master, so that master has all the changes and can be used as the base for the new branch (cascading merge, example ⧉).

build.publish.jdk¶ ⧉

This repository is responsible for publishing the JetBrains Runtime Environment ⧉ to GitHub and the Nexus repository. It is needed by the download-jbr task of the mps-gradle-plugin ⧉.

  • Create a new branch mps/MPS_VERSION and update the file gradle.properties ⧉. To find the new version, open MPS, go to About MPS, and read the Runtime version. On a Mac, you can also open the file jbr/Contents/Info.plist in the MPS installation.
  • Make sure that the published flavor still exists for the JBR version. You can find the newest JBR version for the corresponding IntelliJ platform here (example for JBR 17 ⧉).
  • Create a PR (example ⧉) and merge it into master. If you update a maintenance MPS version, use the existing branch as the target branch.
  • If the downloadJBR task from the mps-gradle-plugin ⧉ doesn't work anymore, for example due to a change in the structure of the JBR or a different naming convention, create a PR for the v1.x ⧉ branch in the plugin (example PR ⧉).
  • If it doesn't exist: create a branch for the old master branch, named mps/MPS_VERSION.
  • If everything worked, you should find the artifact on the Nexus server (example ⧉).

build.publish.mps¶ ⧉

This repository is responsible for publishing MPS to GitHub and the Nexus repository. It is necessary to download MPS in the build script (example) which can then be set as the home directly for the Ant build script (example ⧉).

  • Create a new branch mps/MPS_VERSION and update ext.mpsMajor and ext.mpsBuild to MPS_VERSION in build.gradle ⧉.
  • Check that all the JARs that are published still exist and were not removed or renamed. Change the paths accordingly and update the README.
  • Optional: Add this new information to the MPS Platform Docs in Reference->Included Libraries ⧉.
  • Create a PR (example) and merge it into master. If you update a maintenance MPS version, use the existing branch as the target branch (example ⧉).
  • If it doesn't exist: create a branch for the old master branch, named mps/MPS_VERSION.
  • If everything worked, you should find the artifact on the Nexus server (example ⧉).

MPS-Extensions¶ ⧉

  • Check if there is already an existing branch mps/MPS_VERSION to start with.
  • Update jbrVersion and ext.mpsMajor in build.gradle ⧉
  • Follow the migration guide for IETS3 ⧉ unless not applicable.
  • Update the badge in README.md ⧉ to show the newly supported MPS version.
  • Update the current supported versions in the documentation.
  • Check all sandboxes and actions in the project manually to ensure that no errors are thrown.
  • Check that no (new) error messages appear in the log file ⧉. If the error/warning is fixable has to be decided on a case-by-case basis.
  • Create a PR and merge it into master (example). If you update a maintenance MPS version, use the existing branch as the target branch (example ⧉).

mbeddr.core¶ ⧉

  • Read the Mbeddr section ⧉, especially how to run the migrations in all projects using BigProject.
  • Follow the MPS-Extensions Guide unless not applicable.
  • Follow the migration guide for IETS3 ⧉ unless not applicable.
  • For the manual testing part, focus especially on the tools and actions.
  • If it doesn't exist: create a branch for the old master branch, named maintenance/MPS_VERSION.

iets3.opensource¶ ⧉

  • When possible, merge open pull requests first.
  • Create a new branch: feature/MPS_VERSION (e.g., feature/mps20212)
  • Update jbrVersion, major, minor, ext.mpsVersion, mbeddrVersion in build.gradle ⧉.
  • Regenerate the all scripts build file (build-allScripts.xml) with a single commit, and regenerate the build model.
  • Remove references to languages that don’t exist anymore, for example when a language was removed in a different platform.
  • Execute migrations (Migrations → Run Migration Assistant).
  • Update the README (currently supported version).
  • Create a pull request (example) for master. If you update a maintenance MPS version, use the existing branch as the target branch (example ⧉).
  • Fix tests that don't work. Remove the commit with the migration if necessary and run the migration again after the fixes.
  • If it doesn't exist: create a branch for the old master branch, named maintenance/MPS_VERSION.
  • Update the base branch of the pull requests that were not merged yet to the old master branch.

Getting Help

This section gives some hints on how to find information and get help if you are getting stuck.

Things to read about the new MPS version:

Things to read about the new IntelliJ platform version in case there is a change:

For getting other help, please ask @apann ⧉ on Slack. He can send you to the right people if necessary.

Things to Test

Despite having automatic tests, there are still a lot of topics that should be manually tested:

  • Can I run tests?
  • Can I run tests in the same process?
  • Do I see any suspicious fatal error messages in the bottom right corner?
  • Do actions with dynamic texts (e.g., Run -> Run KernelF tests) still work?
  • Do different graphical notations still work? (e.g., tables, vertical and horizontal lines)
  • Do I see any changes in the editor of the collections test suite (many tests)?
  • Does anything bad happen when I click Tools -> Reload all classes?
  • Does anything bad happen when I restart MPS?

Additional Tips

  • To make sure that all resolve infos are up to date, execute File → Force Save All before pushing.
    • If you use the linters from mps-qa ⧉: there is a linter to check the resolve infos
  • Run git clean -dfx if you run into any troubles and need to remove all files including the generated ones.
  • When you update the dependencies in the build script and nothing happens, execute: ./gradlew setup --refresh-dependencies or gradle.bat setup --refresh-dependencies on Windows.
  • Do not disable languages/features because you can't fix the issue. Ask for help!
  • The decision which MPS platforms are maintained are which are not is decided internally based on usage in projects. Please ask, if you have any questions.
Last update: September 3, 2023

Comments