Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add forc-migrate tool #6790

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Add forc-migrate tool #6790

wants to merge 4 commits into from

Conversation

ironcev
Copy link
Member

@ironcev ironcev commented Dec 16, 2024

Description

This PR introduces forc-migrate, a Forc tool for migrating Sway projects to the next breaking change version of Sway.

The tool addresses two points crucial for code updates caused by breaking changes:

  • it informs developers about the breaking changes and assists in planing and executing the migration.
  • it automatically changes source code where possible, reducing the manual effort needed for code changes.

Besides adding the forc-migrate tool, the PR:

The migration for the references feature, migrating ref mut to &mut, is added only temporarily, to demonstrate the development and usage of automatic migrations that alter the original source code. This migration will be removed before the next breaking change release, because the references feature will not be a part of it.

The intended usage of the tool is documented in detail in the "forc migrate" chapter of The Sway Book: Forc reference > Plugins > forc_migrate. (The generated documentation has issues that are caused by the documentation generation bug explained in #6792. These issues will be fixed in a separate PR that will fix it for all the plugins.)

We expect the forc-migrate to evolve based on the developer's feedback. Some of the possible extensions of the tool are:

  • adding additional CLI options, e.g., for executing only specific migration steps, or ignoring them.
  • passing parameters to migration steps from the CLI.
  • migrating workspaces.
  • migrating other artifacts, e.g., Forc.toml files or contract IDs.
  • migrating between arbitrary versions of Sway.
  • migrating SDK code.
  • etc.

forc-migrate also showed a clear need for better infrastructure for writing static analyzers and transforming Sway code. The approach used in the implementation of this PR should be seen as a pragmatic beginning, based on the reuse of what we currently have. Some future options are discussed in the comments of #6779.

Demo

forc migrate show

Shows the breaking change features and related migration steps. This command can be run anywhere and does not require a Sway project.

Breaking change features:
  - storage_domains    (https://github.com/FuelLabs/sway/issues/6701)
  - references         (https://github.com/FuelLabs/sway/issues/5063)

Migration steps (1 manual and 1 semiautomatic):
storage_domains
  [M] Review explicitly defined slot keys in storage declarations (`in` keywords)

references
  [S] Replace `ref mut` function parameters with `&mut`

Experimental feature flags:
- for Forc.toml:  experimental = { storage_domains = true, references = true }
- for CLI:        --experimental storage_domains,references

forc migrate check

Performs a dry-run of the migration on a concrete Sway project. It outputs all the occurrences in code that need to be reviewed or changed, as well as the migration time effort:

info: [storage_domains] Review explicitly defined slot keys in storage declarations (`in` keywords)
  --> /home/kebradalaonda/Desktop/M Forc migrate tool/src/main.sw:19:10
   |
...
19 |     y in b256::zero(): u64 = 0,
   |          ------------
20 |     z: u64 = 0,
21 |     a in calculate_slot_address(): u64 = 0,
   |          ------------------------
22 |     b in 0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20: u64 = 0,
   |          ------------------------------------------------------------------
   |
   = help: If the slot keys used in `in` keywords represent keys generated for `storage` fields
   = help: by the Sway compiler, those keys might need to be recalculated.
   = help:  
   = help: The previous formula for calculating storage field keys was: `sha256("storage.<field name>")`.
   = help: The new formula is:                                          `sha256((0u8, "storage.<field name>"))`.
   = help:  
   = help: For a detailed migration guide see: https://github.com/FuelLabs/sway/issues/6701
____

Migration effort:

storage_domains
  [M] Review explicitly defined slot keys in storage declarations (`in` keywords)
      Occurrences:     3    Migration effort (hh::mm): ~00:06

references
  [S] Replace `ref mut` function parameters with `&mut`
      Occurrences:     0    Migration effort (hh::mm): ~00:00

Total migration effort (hh::mm): ~00:06

forc migrate run

Runs the migration steps and guides developers through the migration process.

Checklist

  • I have linked to any relevant issues.
  • I have commented my code, particularly in hard-to-understand areas.
  • I have updated the documentation where relevant (API docs, the reference, and the Sway book).
  • I have added tests that prove my fix is effective or that my feature works.
  • I have added (or requested a maintainer to add) the necessary Breaking* or New Feature labels where relevant.
  • I have done my best to ensure that my PR adheres to the Fuel Labs Code Review Standards.
  • I have requested a review from the relevant team or maintainers.

@ironcev ironcev self-assigned this Dec 16, 2024
@ironcev ironcev added forc forc-migrate Everything to do with the forc-migrate tool. labels Dec 16, 2024
@ironcev
Copy link
Member Author

ironcev commented Dec 17, 2024

To try out the forc migrate tool locally:

  1. Pull and checkout the ironcev/forc-migrate-tool branch.
  2. Install the tool from the Sway repository: cargo install --path ./forc-plugins/forc-migrate

For the detailed documentation on migration and the usage of the tool see the scripts/mdbook-forc-documenter/examples/forc_migrate.md in this PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
forc forc-migrate Everything to do with the forc-migrate tool.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant