diff --git a/docs/book/src/forc/plugins/forc_migrate.md b/docs/book/src/forc/plugins/forc_migrate.md index 1f300857c33..fb2a30010b9 100644 --- a/docs/book/src/forc/plugins/forc_migrate.md +++ b/docs/book/src/forc/plugins/forc_migrate.md @@ -8,7 +8,7 @@ The Forc plugin for migrating Sway projects to the next breaking change version For example, let's say that your Sway project is on the version _v0.66.1_, and that the latest v0.66 version is _v0.66.42_. You should first update your Fuel toolchain to the version _v0.66.42_ of `forc`, and compile your project with that version: -``` +```text fuelup component add forc@0.66.42 ``` @@ -18,13 +18,13 @@ Sway guarantees that all the versions with the same minor version, _0.66_ in the Once you've installed the latest non-breaking version of `forc-migrate`, use the `show` command to make yourself familiar with the upcoming breaking changes: -``` +```text forc migrate show ``` A typical output of the `show` command will look like this: -``` +```text Breaking change features: - storage_domains (https://github.com/FuelLabs/sway/issues/6701) - references (https://github.com/FuelLabs/sway/issues/5063) @@ -42,6 +42,7 @@ Experimental feature flags: ``` The output will contain: + - the upcoming breaking change features, `storage_domains` and `references` in this example, - their tracking issues on GitHub, with detailed migration guides, - and the migration steps potentially required to migrate existing code. @@ -58,7 +59,7 @@ First, we will go to the folder that contains `my_project`, e.g.: `cd my_project Before migrating the code, make sure that the project builds without any errors by running: -``` +```text forc build ``` @@ -66,16 +67,17 @@ forc build Next, let's `check` the project first. The `check` command will dry-run the migration steps. It will not do any changes in code, but will provide a detailed information of all the places in code that need to be either reviewed or changed during the migration process. The `check` command will also provide a rough time estimate for the migration. -``` +```text forc migrate check ``` The output of the `check` command will end in a summary of the migration effort, containing: + - the number of occurrences of a particular migration step in the project's code, - the rough migration effort estimate for each migration step, - and the rough total migration effort. -``` +```text Migration effort: storage_domains @@ -90,11 +92,12 @@ Total migration effort (hh::mm): ~01:36 ``` Before the summary, instructions will be shown for each migration step. A typical instruction output for a single migration step will contain: + - the name of the step, - the places in code affected by the migration step, - and the short help with a link to the detailed migration guide. -``` +```text info: [references] Replace `ref mut` function parameters with `&mut` --> my_project/src/main.sw:30:51 | @@ -121,7 +124,7 @@ Before running the migrations on the project itself, **first update the project In our example, the `my_project`'s `Forc.toml` file will have the `[dependencies]` section similar to this one: -``` +```toml [dependencies] std = { git = "https://github.com/FuelLabs/sway", tag = "v0.66.1" } third_party_lib = { git = "https://github.com/ThirdParty/swaylib", tag = "v1.0.0" } @@ -129,7 +132,7 @@ third_party_lib = { git = "https://github.com/ThirdParty/swaylib", tag = "v1.0.0 Assuming that the `third_party_lib` version compatible with Sway v0.67.0 is the version v2.0.0 we will end up in the following changes: -``` +```toml [dependencies] std = { git = "https://github.com/FuelLabs/sway", tag = "v0.67.0" } # v0.66.1 -> v0.67.0 third_party_lib = { git = "https://github.com/ThPa/swaylib", tag = "v2.0.0" } # v1.0.0 -> v2.0.0 @@ -139,7 +142,7 @@ Run `forc build` to make sure that the project still compiles. **At this point, To compile the project with experimental features, you can take the feature flags from the `forc migrate show` output, and place them either in the `[build-profile]` section of the projects `Forc.toml` file, or pass them to `forc build` via the command line. -``` +```text Experimental feature flags: - for Forc.toml: experimental = { storage_domains = true, references = true } - for CLI: --experimental storage_domains,references @@ -147,7 +150,7 @@ Experimental feature flags: In the remaining part of this tutorial, we will be passing the feature flags via the command line. E.g.: -``` +```text forc build --experimental storage_domains,references ``` @@ -155,7 +158,7 @@ forc build --experimental storage_domains,references Once the `my_project` successfully builds with updated dependencies, we can `run` the migration steps on it. E.g.: -``` +```text forc migrate run --experimental storage_domains,references ``` @@ -168,12 +171,13 @@ The `run` command will execute the migration steps, and guide you through the mi | Changing | The step is automatically changing the code. There might be additional manual actions needed. | At the end of the `run`, the migration will either guide you to: + - `Continue` the migration process by performing the manual actions and re-running the `forc migrate run` afterwards, - or will mark the migration process as `Finished`. At this point, your project will be compatible with the next breaking change version of Sway. ## Migrating workspaces -To migrate a workspace, you will need to migrate each workspace member separately, following the above procedure. The projects should be migrated in order of their dependencies. +To migrate a workspace, you will need to migrate each workspace member separately, following the above procedure. The projects should be migrated in order of their dependencies. ## Additional after-migration steps