MPS
Space shortcuts
Child pages
  • Migration to 2020.1
ConfigureSpace tools
Skip to end of metadata
Go to start of metadata

Automated migrations in 2020.1


MPS 2020.1 comes with four migrations that will update your projects to the latest versions of jetbrains.mps.baseLanguage, jetbrains.mps.lang.quotation and jetbrains.mps.lang.editor:

  1. UpdateSingleLineCommentToUseLinePerComment will update instances of SingleLineComment to use a different child to hold the textual description of the comment. The comment can now only hold a single line of text, so the migration has to split single line comments that spread across several lines.

    -> becomes ->

  2. MigrateTryStatement will update instances of TryCatchStatement and TryFinallyStatement to TryUniversalStatement, which allows for JDK 8 features, such as multiple exceptions in a single catch clause and with-resource capabilities.
  3. LightQuotation_InitProperyExpression - wraps property initialisers of light quotations into instances of NodeBuilderPropertyExpression.
  4. Migrate_MergeNamedAndDefaultMenus will upside definitions of transformation and substitute menus to the new concepts. Transformation menus (TM) and Substitute menus (SM) were refactored so that Named and Default concept variants were merged into one concept each: TransformationMenu and SubstitutionMenu, respectively. Distinction between default and named variants is still there but is now handled by the type property of each concept instead of having a separate root concept for them.

All four migrations are re-runnable and so can be run repetitively if a merge brings non-migrated code into your branch.

Icon

Be sure that you update the VCS settings before merging your project (see below for details). Also, follow the Recommended migration strategy described further down in this document, otherwise you may run into problems easily.

Update the VCS settings

The MPS merge driver has been improved. Make sure your merge driver as well as the VCS settings are up-to-date before merging conflicting branches. The VCS subsystem of MPS needs Git to be configured in a certain way in order to function properly. An outdated VCS configuration of a project is indicated to the user upon opening the project. Check out full details at the VCS documentation page, if you want to know more details.

The user can trigger the "Update" action from the popup:

 

It can alternatively be started from the VCS menu:

When the installation completes, you can rely on the VCS system to be ready.

Recommended migration strategy

Icon

Merging two branches that both have been migrated to MPS 2020.1 separately is likely to give you headaches. Avoid it!

Otherwise this will happen to you and your loved ones:

  1. All single line comments that spread across several lines will be split into new instances of single line comments, which will be different nodes in each branch and will be in conflict.
  2. New instances of TryUniversalStatement in both branches will be in conflict if there are additional changes inside this statement.
  3. Light quotations that the migration enhances with the NodeBuilderPropertyExpression wrappers, will be in conflict.
  4. All Transformation menus and Substitute menus will be in conflict and you will need to accept one or the other (root node's concept has changed and there are new child nodes in the menus). This is because the root nodes of Transform/Substitute menusM and SM changed their concepts and are in fact different instances. You can merge them one by one and in case the menu was not changed in either branch OR the menu changed in just one branch you can use the Accept Yours or Accept Theirs strategy as appropriate.

We strongly recommend you to migrate all your branches to MPS 2020.1 in a single step.

Icon

This document overrides the information given in the Migration with branching documentation page and should be followed when migrating to MPS 2020.1.

 

The prefered scenario:

  1. Merge all the branches to master.
  2. Migrate the master using the migration assistant.
  3. Run the Migrate try statement enhancement script.
  4. Start new branches off the migrated master.

The "Run the Migrate try statement enhancement script" step needs a bit of explanation. The normal migration of try statements works in a defensive way and avoids migrating in situations that can potentially lead to broken code. These are typically try statements in generator template fragments, macros, commented out nodes or inside quotations. To avoid the need to manually update the code that the migration skips (the not-migrated nodes are reported by the migration, so you will see a list of them) we provide an enhancement script called Migrate try statement to attempt to migrate those complicated cases. It may, however, lead to broken code, so manual verification of the result is needed.

Alternative migration strategy

If you can't help it and have to merge a not-migrated branch into a migrated master, you should follow the scenario described in this section:

  1. Resolve merge conflicts
  2. Execute re-runable migrations
  3. Manually check the diff
  4. Run the "Migrate try statement" enhancement script
  5. Manually check the diff
  6. Commit

We will discuss these topics in more detail now.

1. Resolve merge conflicts

Conflicts in editor.mps file (jetbrains.mps.lang.editor)

This may happen if you try to merge a non-migrated branch to a migrated branch and your non-migrated branch contains some changes to the same menu that you have migrated in the other branch. In this case it's recommended to Accept Yours (keep the migrated menu) and apply the modifications done in the other branch manually. 

Conflicts in SingleLineComment (jetbrains.mps.baseLanguage)

A merge conflict will be reported for all single-line comments that have been modified in the branch.

The single-line comments that have not been changed in the branch will be taken from the master and so will have been migrated already. These can be auto-resolved using the appropriate tool button.

The remaining conflicting changes have to be migrated manually, perhaps by accepting the changes from the branch (accept theirs). Not migrated instances of SingleLineComment will thus be re-inserted into the code.

Special care must be taken for single-line comments spreading across multiple lines, as is in the last comment in the illustrating code above. Since the migration separated the additional lines into standalone instances of SingleLineComment, which are hanging below the original SingleLineComment instance, and since merging the changes from the branch will only affect the original (top) instance of SingleLineComment, the lines below will be duplicating the text of the comment.

The duplicating trailing single-line comments can be deleted. Some of the lines, however, may hold changes to the text of the comment coming from the master branch. These must be manually copied into the single-line comment and only then the trailing comment can be deleted.

This way you resolve all the conflicts and close the dialog. The code now, however, contains not-migrated instances of SingleLineComment coming from the branch.

Conflicts between not-migrated TryCatchStatement/TryFinallyStatement and already migrated TryUniversalStatement (jetbrains.mps.baseLanguage)

A merge conflict will be reported if there were changes inside the non-migrated or the migrated try statement.

There are 3 posible cases:

  1. changes were only inside the migrated try statement - This is the simplest case and there should be no conflict. Just accept changes if they were not accepted automatically.
  2. changes were only inside not-migrated try statement - Here you should accept the changes from the not-migrated branch and ignore those from the migrated one (actually there are no meaningful changes to loose, just the migration that you'll repeat in the next step, anyway).
  3. changes were inside the try statements in both branches - This is the most complicated case. Choose one of the branches (not-migrated or migrated) from which you'll accept the changes. We suggest to use the migrated branch but sometimes most of the changes are in not-migrated, in which case you should perhaps choose that one. Then accept the changes in try statements from the chosen branch and ignore the changes in try statements from the other branch. Finally manually copy/paste the changes from the other branch. You can conveniently do it directly in the 3-way merge dialog: copy the statements from the right or the left editor and then paste into the center one.
Icon

Avoid using the auto-resolve buttons of the merge dialog for try-statements. This can leave a VCS marker in not the migrated branch that offers to add an inner change (e.g. statements inside a try-statement) to an invalid old role.

Conflicts between not-migrated and migrated light quotations

Depending on the changes made to either of the branches or both of them, handle the situation in a way similar to the previous case.

2. Execute re-runable migrations

Since the master after merge may contain code that has not been migrated, the migrations have to be re-run to upgrade the code to MPS 2020.1. Run the Execute Re-Runnable Migrations action from the menu to get that done easily.

3. Manually check the diff

4. Run the "Migrate try statement" enhancement script

Just like in the normal migration scenario, run the Migrate try statement enhancement script, to attempt to migrate automatically the cases that the migration skipped to avoid breaking code.

5. Manually check the diff

Since the previous step could have broken some code, you should inspect the changes manually and correct them eventually.

6. Commit

You are done. The code can now be committed.

 


 

  • No labels