docs(canister-management): add canister migration guide, improve subnet selection, reorder sidebar#245
Open
marc0olo wants to merge 10 commits into
Open
docs(canister-management): add canister migration guide, improve subnet selection, reorder sidebar#245marc0olo wants to merge 10 commits into
marc0olo wants to merge 10 commits into
Conversation
Addresses all issues raised in #233: - Rename "Colocation with an existing canister" to "Colocation via proxy canister" and expand it with three targeted fixes: - Clarify that --proxy and --subnet are mutually exclusive - Add the full ProxyArgs/ProxyResult Candid interface so developers know exactly what their proxy canister must implement - Explain the cycles model: --cycles passes a value through ProxyArgs.cycles and is paid from the proxy canister's own balance, not the caller's wallet - Fix the "by default" phrasing in troubleshooting: replace with "without using icp canister migrate-id" - Add a direct link to the canister migration guide in the troubleshooting entry and in Next steps
|
🤖 Here's your preview: https://lvbky-nyaaa-aaaam-ai7tq-cai.icp0.io |
marc0olo
commented
May 12, 2026
…tion guide Address PR #245 review feedback and source-verified inaccuracies: - Cycles model: replace "from your wallet" with "from your identity's balance on the cycles ledger" (wallet is a deprecated dfx concept) - Migration description: fix step ordering — snapshot deletion on target belongs within the state transfer phase, before copying settings, not after; add the missing "stop the target canister" prerequisite for migrate-id; add the cycles burn warning (source cycles burned, target needs funding in advance) - Next steps snapshot link: add section anchor pointing directly to the state-transfer example; sharpen the label - Upstream comment: add proxy.rs and canister-migration.md references
Member
Author
|
Feedback addressed:
|
…oss-references Add docs/guides/canister-management/canister-migration.md covering both migration paths: snapshot transfer (new canister ID) and full migration with ID preservation via icp canister migrate-id. The guide documents the step ordering that matters for correctness — snapshot deletion on the target before migrate-id, target must be stopped, source cycles are burned — and includes interruption recovery and NNS controller cleanup. Update cross-references: - subnet-selection.md: replace external cli.internetcomputer.org links with internal links to canister-migration.md - snapshots.md: add canister migration to Next steps - large-wasm.md: bump sidebar order from 9 to 10 to accommodate canister-migration at order 9 (after subnet-selection)
…llout - subnet-selection troubleshooting: shorten the "ID must be preserved" bullet to one sentence + link; detail belongs in the migration guide - canister-migration: add :::danger callout after the load-bearing ID cases to make permanent, irreversible loss visible before users choose an approach - subnet-selection Next steps: tighten snapshot label to "to another canister" (download/upload works for any target, not just cross-subnet) - snapshots Next steps: same label fix
…ghten copy
- Remove load_canister_snapshot parenthetical from snapshots.md and
canister-migration.md: the protocol-level cross-canister same-subnet
restore is real (per IC interface spec) but the icp-cli doesn't expose
it and we have no guide for it; replace with the accurate icp-cli-level
constraint ("snapshot must exist on target before restore")
- Trim subnet-selection troubleshooting bullet to one sentence + link
- Snapshots Next steps: "to another canister" instead of "to a canister
on a different subnet" (download/upload works for any target canister)
…uide Two corrections in the "Choosing your approach" section: - Replace "load-bearing" with "whether the canister ID can change" and "The canister ID cannot change when" — avoids informal construction metaphor, says the same thing in plain ICP terms - Rewrite danger callout: "no recovery path" was wrong. Snapshot transfer retains the source canister, so the original tECDSA/vetKeys remain accessible through it until the source is deleted. Callout now explains the recovery window (stop target, switch back, do full migration) and names the actual point of no return (source canister deleted).
…on section Sidebar reorder (core ops → build quality → deployment topology): - cycles-management: 7 → 4 (fundamental, not advanced) - snapshots: 5 unchanged (stays after cycles, supports upgrade safety) - optimization: 4 → 6 - reproducible-builds: 6 → 7 - large-wasm: 10 → 8 (closes build quality cluster) - subnet-selection: 8 → 9 - canister-migration: 9 → 10 lifecycle.mdx migration section: replace 22-line duplicate (table + bullets + GitHub raw link) with a two-sentence pointer to canister-migration.md; add subnet selection and canister migration to Next steps
marc0olo
changed the title
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
1 participant
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.
Closes #233.
Summary
Subnet selection (
guides/canister-management/subnet-selection.md):--proxysection rewritten: notes--proxy/--subnetmutual exclusivity; adds the exactProxyArgs/ProxyResultCandid interface; clarifies cycles come from the proxy canister's own balance, not the caller's identity balance on the cycles ledgerNew page: Canister migration (
guides/canister-management/canister-migration.md, sidebar order 10):icp canister migrate-id(ID preserved, source deleted):::dangercallout explains the recovery window accurately: state and keys split between canisters after snapshot transfer; recovery possible until source is deleted; permanent once source is gonemigrate-id; source cycles burned; target must be stopped; NNS migration canister controller must be removed after--resume-watch,--skip-watch) documentedCanister lifecycle (
guides/canister-management/lifecycle.mdx):[principal]link to point toconcepts/principals.mdinstead ofconcepts/canisters.mdCanister snapshots (
guides/canister-management/snapshots.md):load_canister_snapshotprotocol detail; replaced with accurate icp-cli-level constraintSidebar reorder (core operations → build quality → deployment topology):
Sync recommendation
canister-migration.md:informed by dfinity/icp-cli docs/guides/canister-migration.md; dfinity/icp-cli docs/reference/cli.mdsubnet-selection.md:informed by dfinity/icp-cli docs/guides/deploying-to-specific-subnets.md; dfinity/icp-cli docs/guides/canister-migration.md; dfinity/icp-cli crates/icp-canister-interfaces/src/proxy.rs; dfinity/icp-cli crates/icp-cli/src/operations/proxy.rs; dfinity/icp-cli docs/reference/cli.md