-
Notifications
You must be signed in to change notification settings - Fork 5.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
17 additions
and
13 deletions.
There are no files selected for viewing
This file contains 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
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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] | ||
``` | ||
|
||
|
@@ -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,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 | ||
|
@@ -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,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 | ||
|
@@ -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 | ||
``` | ||
|
||
|
@@ -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 | ||
|
||
|