Fix automatically generated documentation for forc commands and plugins
#6792
Labels
Comments
IGI-111
pushed a commit
that referenced
this issue
Jan 20, 2025
## 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: - extends `Diagnostic` to support migration diagnostics aside with errors and warnings. - changes `swayfmt` to support generating source code from arbitrary lexed trees. The change is a minimal one done only in the parts of `swayfmt` that are executed by migration steps written in this PR. Adapting `swayfmt` to fully support arbitrary lexed trees will be done in #6779. The migration for the `references` feature, migrating `ref mut` to `&mut`, is developed only partially, to demonstrate the development and usage of automatic migrations that alter the original source code. 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. - not allowing updates by default, if the repository contains modified or untracked files. - 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 #6836. ## 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 (#6701) - references (#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: #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 - [x] I have linked to any relevant issues. - [x] I have commented my code, particularly in hard-to-understand areas. - [x] I have updated the documentation where relevant (API docs, the reference, and the Sway book). - [x] If my change requires substantial documentation changes, I have [requested support from the DevRel team](https://github.com/FuelLabs/devrel-requests/issues/new/choose) - [ ] 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. - [x] I have done my best to ensure that my PR adheres to [the Fuel Labs Code Review Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md). - [x] I have requested a review from the relevant team or maintainers.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
The
mdbook-forc-documenterplugin formdbookis not compatible with the output of the newest version ofclap, which it parses in a simple manner to generate documentation pages forforccommands and plugins.Below are some of the issues. All of them can be seen on the official documentation page of the current Sway version:
https://fuellabs.github.io/sway/v0.66.5/book/
The proposal is to also add a check to
mdbook-forc-documenterto ensure that the version ofclapdidn't change. In case of a change, we would manually check the validity of the output and adapt themdbook-forc-documenter's unit tests. Note that the documenter has unit tests, but they are all testing proper text transformations during rendering, which assumes that the input is in a certain format, which can potentially change when theclapversion changes.All the tools have the name "Forc"
E.g.:
Subcommands are not recognized and generated as a single text
E.g.:
Short text for examples is rendered as Heading 1
E.g.:
The text was updated successfully, but these errors were encountered: