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:
- 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 ->
- 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.
- LightQuotation_InitProperyExpression - wraps property initialisers of light quotations into instances of NodeBuilderPropertyExpression.
- 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.
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
We strongly recommend you to migrate all your branches to MPS 2020.1 in a single step.
The prefered scenario:
- Merge all the branches to master.
- Migrate the master using the migration assistant.
- Run the Migrate try statement enhancement script.
- 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:
- Resolve merge conflicts
- Execute re-runable migrations
- Manually check the diff
- Run the "Migrate try statement" enhancement script
- Manually check the diff
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:
- 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.
- 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).
- 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.
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.
You are done. The code can now be committed.