| name | mps-aspect-migrations |
| description | Use when authoring or debugging MPS migration scripts that upgrade user models after a language definition changes — covers jetbrains.mps.lang.migration (MigrationScript class-based, PureMigrationScript declarative, MoveConcept/MoveContainmentLink/MoveReferenceLink/MoveProperty, ordering via OrderDependency, data exchange via putData/getData, RefactoringLog, ConceptMigrationReference) and jetbrains.mps.lang.script Enhancement Scripts (MigrationScript with MigrationScriptPart_Instance, ExtractInterfaceMigration, FactoryMigrationScriptPart, CommentMigrationScriptPart) — when a model needs version-gated upgrade, concept rename or removal, link or property rename, instance-level transformation, or composition of migration steps. |
| type | reference |
MPS Migrations Aspect
Two complementary languages upgrade user models when language definitions change:
jetbrains.mps.lang.migration (l:90746344-04fd-4286-97d5-b46ae6a81709) — core migration language with MigrationScript (class-based, programmatic) and PureMigrationScript (declarative, structural).jetbrains.mps.lang.script (l:0eddeefa-c2d6-4437-bc2c-de50fd4ce470) — Enhancement Scripts that apply concept-instance transformations, used for richer per-node updates.
These address the same problem at different abstraction levels: lang.migration handles structural language refactorings (concept moves/renames, removed concepts); lang.script handles content transformations (modifying properties, children, references of existing instances).
Critical Directives
- Do not confuse the two
MigrationScript concepts. One is in lang.migration (BL ClassConcept, version-gated). The other (alias "Enhancement Script") is in lang.script (instance-level transformer). Always disambiguate by language ref.
fromVersion is the version migrated FROM, not to. Bump the language's version integer in the .mpl solution manifest whenever you add a migration step.- Model naming is convention-driven and load-bearing.
lang.migration scripts live in <language.fqn>.migration. lang.script Enhancement Scripts live in <language.fqn>.scripts. MPS discovers them by these names at startup.
- Migration scripts run in dependency order, determined by
OrderDependency / ExecuteAfterDeclaration. Always declare ordering when the result of one script feeds the next.
- Do not hand-edit serialized
.mps migration files. Use MPS MCP node tools.
Workflow
- Decide form:
PureMigrationScript for structural moves/renames/removals; MigrationScript for programmatic transforms; Enhancement Script for instance-level updates. See references/form-selection.md.
- Create or locate the migration model with
mps_mcp_create_model: <language.fqn>.migration for lang.migration (aspect ID migration); <language.fqn>.scripts for Enhancement Scripts (aspect ID scripts). Both aspect IDs are case-sensitive and carry no @ suffix — see aspect-model-stereotypes.md. Add the used languages required for that form.
- Bump the language
version integer in the .mpl and set fromVersion on the new script to the previous version.
- Build the script body (declarative parts, BL
execute() method, or MigrationScriptPart_Instance updater) using the JSON blueprints in references/json-blueprints.md.
- Wire ordering (
OrderDependency / ExecuteAfterDeclaration) and data flow (putData / getData) if needed.
- Validate via
mps_mcp_check_root_node_problems, then run the migration on a test model.
Related Skills
mps-aspect-typesystem, mps-aspect-constraints — when a migration depends on or alters typesystem rules.mps-aspect-generator — when version changes also touch generator templates.mps-quotations — for QuotationConsequence consequence bodies inside MigrationScript.execute().mps-model-manipulation — BL + smodel constructs used inside MigrationScript.execute() and Enhancement Script updaters.
Reference Index
- Form selection guide — open before authoring to pick between
PureMigrationScript, MigrationScript, and Enhancement Script for the change at hand. Covers ordering, data flow, and model setup. See references/form-selection.md.
lang.migration concept reference — open when you need exact members, cardinalities, properties, or concept IDs for MigrationScript, PureMigrationScript, IMigrationUnit, ordering and data-exchange concepts, and RefactoringLog. See references/lang-migration-reference.md.PureMigrationPart, node references, and move specializations — open when defining concept/link/property renames or composing migration units via IncludeMigrationPart. See references/pure-migration-parts.md.MigrationScript execute-body constructs — open when writing the BL body of a programmatic MigrationScript: pattern variable references, ConsequenceFunction vs QuotationConsequence, ConceptMigrationReference. See references/migration-script-body.md.lang.script Enhancement Scripts — open when iterating over concept instances to update properties/children/references, or when wiring ExtractInterfaceMigration, FactoryMigrationScriptPart, or CommentMigrationScriptPart. See references/enhancement-scripts.md.- Verified JSON blueprints — open when constructing a real migration as JSON for MCP tools. Includes
MigrateReferences, SNodeTypeCastExpression_completelyRemoved, and Migrate_ParametrizedIntentions. See references/json-blueprints.md.
- Concept ID quick reference — open when assembling JSON that requires
conceptReference strings for lang.migration and lang.script. See references/concept-ids.md.
FIND_INSTANCES recipes — open to enumerate existing migration scripts or enhancement scripts in the project. See references/find-instances.md.
