Skip to content

Commit

Permalink
Fix Markdown issues
Browse files Browse the repository at this point in the history
  • Loading branch information
ironcev committed Dec 16, 2024
1 parent d16a7be commit 50c4ae8
Showing 1 changed file with 17 additions and 13 deletions.
30 changes: 17 additions & 13 deletions docs/book/src/forc/plugins/forc_migrate.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 [email protected]
```

Expand All @@ -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)
Expand All @@ -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.
Expand All @@ -58,24 +59,25 @@ 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
```

### Check the migration summary

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
Expand All @@ -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
|
Expand All @@ -121,15 +124,15 @@ 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" }
```

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
Expand All @@ -139,23 +142,23 @@ 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
```

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
```

### Run the migrations

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
```

Expand All @@ -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

Expand Down

0 comments on commit 50c4ae8

Please sign in to comment.