bb7c99b24a
## Description This PR: - implements partial equivalence in the `core::ops`, as explained in detail in #6883. The implementation is opt-in and behind the `partial_eq` experimental feature flag. - implements `forc migrate` migration steps for automatic migration to `partial_eq` feature. - extends the infrastructure for writing `forc migrate` migrations. - preserves `Annotation`s on `LexedModule`s in the `LexedProgram`. (Those were before stripped off and not available in the compiled `Programs`. This resulted in loss off `//!` doc-comments that are represented as `doc-comment` annotations.) Extensions in the `forc migrate` infrastructure include: - possibility to postpone migration steps. This allows writing multi-step migrations where the first step is usually early adopting an experimental feature by using `cfg` attributes in code. This possibility is crucial for migrating our own codebase where we want to early-adopt and test and stabilize experimental features. - possibility to match elements on both mutable and immutable parsed trees. The initial assumption that immutable matching on typed trees will always be sufficient does not hold. Experimental `cfg` attributes can remove parts of typed trees that might be needed in analysis. - `LexedLocate(As)Annotated` for easier location and retrieval of `Annotated` elements. - additional implementations of existing traits. - additional `Modifier`s for modifying existing elements in the lexed tree. - `New` struct for convenient creation of often needed lexed tree elements. Note that we do not expect migrations to generate large new parts of lexed trees, but mostly to modify or copy and modify existing ones. Almost all of the changes in the Sway files are done automatically by the migration steps. The only manual change was in the `core` library (`std` library is also automatically migrated) and in slight extension of two of the tests. Note that some of the tests have `Eq` traits in trait constraints. As explained in the #6883, it is not necessary to change those to `PartialEq`. We might consider changing some of them, for testing purposes, and such a change is done on one of the tests that was testing the behavior of the `Eq` trait. But for the majority of the tests, there is no strict need for switching from `Eq` to `PartialEq`. Rolling `PartialEq` out in the tests provoked three existing issues that will be fixed in separate PRs: #6897, #6898, #6899. ## 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). - [ ] If my change requires substantial documentation changes, I have [requested support from the DevRel team](https://github.com/FuelLabs/devrel-requests/issues/new/choose) - [x] 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. |
||
|---|---|---|
| .. | ||
| examples | ||
| src | ||
| Cargo.toml | ||
| README.md | ||
mdbook-forc-preprocessor
A preprocessor for mdBook to update the Forc commands and plugins section of the Sway book based on the output we get when running forc --help.
This preprocessor is automatically run on every build, as long as the book.toml file contains the preprocessor:
[preprocessor.forc-documenter]
The preprocessor runs with strict mode off by default to enable building the book regardless of errors in the Forc Reference pages. To check if pages should be added or removed, run with the strict environment variable:
MDBOOK_preprocessor__FORC_documenter__STRICT="true" mdbook build docs/book
Usage
Adding a new forc command
Enter a new entry under the Commands section within SUMMARY.md, in this format:
- [forc explore](./forc_explore.md)
Adding a new forc plugin
Do the same as the above, with an extra step of adding an installation step within the CI. The preprocessor needs to be aware of the plugin when building the book, since it is calling forc <plugin> --help to generate the documentation. You can add this installation step within ci.yml and gh-pages.yml.
Removing a forc command
Delete the entry from SUMMARY.md.
Removing a forc plugin
Do the same as the above, with an extra step of removing the installation command within ci.yml and gh-pages.yml.
Adding an example
Create a new Markdown file within scripts/mdbook-forc-documenter/examples, named after the desired forc command or plugin in snake case. The preprocessor automatically detects the example if there is a matching forc command or plugin with the same name as the file name, and includes it in the build.
Removing an example
Delete the Markdown file from within the above examples directory.