feat: add managed migration chains for enhanced migrations#495
Merged
Conversation
Add `mops migrate new/freeze` commands and `[canisters.<name>.migrations]` config to automate Motoko enhanced migration chain management. When `[migrations]` is configured, `mops check` and `mops build` auto-inject `--enhanced-migration` with optional chain trimming via `check-limit` and `build-limit`. A hint is shown on stable check failure suggesting migration creation. Spec: cli/specs/managed-migrations.md Made-with: Cursor
- Sanitize migration name (reject path traversal, spaces, invalid chars) - Extend --enhanced-migration conflict check to [moc].args and [build].args - Pass verbose to prepareMigrationArgs in check-stable for consistency - Validate check-limit/build-limit as positive integers (reject floats) - Use UTC in generateTimestamp for cross-timezone consistency - Eliminate redundant readdirSync in prepareMigrationArgs (pass chainFiles) - Add test for invalid migration name rejection Made-with: Cursor
check-stable also auto-injects --enhanced-migration when [migrations] is configured — align all doc surfaces for consistency. Made-with: Cursor
Kamirus
changed the title
… persistence" Made-with: Cursor
Git doesn't track empty directories, so cp on CI skips them and tests fail with ENOENT when writing into the missing dir. Made-with: Cursor
I didn't understand this part; can you please explain? |
Consolidate 4 fixtures (basic, with-next, trimmed, incompatible) into 2 richer fixtures with 3-migration chains. All tests copy a fixture to a temp dir and apply targeted modifications (remove next-migration, patch mops.toml, overwrite deployed.most) to exercise different scenarios. New snapshot-tested use cases: - migrate new / freeze output - check fails without next migration, passes with it - check with chain trimming (verbose) - build produces .most with full and trimmed chain - stable check failure with migration hint Made-with: Cursor
- "Migration management for enhanced migrations" → "Manage enhanced migration chains" - Clarify in docs that check-limit applies to mops check-stable too Made-with: Cursor
No longer needed — the feature is implemented and documented. Made-with: Cursor
Collaborator
Author
Is this clear from the docs? https://github.com/caffeinelabs/mops/pull/495/changes#diff-2d8661e9a26cf52e64445b6f3bf88e576d2f20e1974c2fb701bc57db1e77f8e1 |
Users can add migrations directly to the chain directory without needing a separate next-migration staging workflow. The `next` field is now only required when using `mops migrate new/freeze`. Made-with: Cursor
Previously check-limit/build-limit only trimmed the frozen chain and the next migration was always appended on top. This meant build-limit=2 with 3 chain + 1 next produced 3 files, but after freezing the same limit produced 2 files — inconsistent output for the same logical state. Now chain + next are merged into one list before applying the limit, so the result is identical regardless of whether the last migration is pending or already frozen. Made-with: Cursor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Managing Motoko enhanced migration chains is entirely manual today. Users must:
--enhanced-migration=<path>in canister argsThis is error-prone and creates friction for any project using enhanced migrations.
Solution
Add first-class migration management to mops via a new
[canisters.<name>.migrations]config section andmops migratecommands.New config
New commands
mops migrate new <Name> [canister]— creates a timestamped migration file in thenextdirectorymops migrate freeze [canister]— moves the next migration into the permanent chainAutomatic
--enhanced-migrationinjectionWhen
[migrations]is configured,mops check,mops build, andmops check-stableautomatically inject--enhanced-migrationpointing to a temp directory that merges the chain + next migration. Explicit--enhanced-migrationin[canisters.*.args],[moc].args, or[build].argsis rejected to prevent conflicts.Chain trimming
check-limitandbuild-limitcontrol how many migrations are passed tomoc. When trimming is active, M0254 warnings are auto-suppressed (-A=M0254). This keeps WASM sizes manageable and speeds up type-checking.Migration hint
When a stable compatibility check fails and
[migrations]is configured, a hint is shown: "You may need a migration. Runmops migrate new <Name>to create one."Scope & limitations
.mostfile management and deployed state tracking are deferred to a follow-up.Test plan
mops migrate newcreates correctly named file with template (snapshot)mops migrate newrejects invalid names (path traversal, spaces, digits-first)mops migrate newerrors when next dir already has a filemops migrate new/freezeerrors when[migrations]not configuredmops migrate freezemoves file from next to chain (snapshot)mops migrate freezeerrors when next is empty or file doesn't sort lastmops checkfails without next migration, passes with it (snapshot —with-nextfixture)mops checkwithcheck-limitshows trimmed chain in verbose output (snapshot)mops buildproduces correct.mostwith full chain (snapshot)mops buildwithbuild-limitproduces trimmed.most(snapshot)[migrations]and--enhanced-migrationin args