Add v2 macros migration guide

commit-id:d5868aee

Author: cptartur

docs/src/SUMMARY.md

@@ -8,6 +8,7 @@
 * [First Steps with Starknet Foundry](getting-started/first-steps.md)
 * [Scarb](getting-started/scarb.md)
 * [Project Configuration](projects/configuration.md)
+* [`snforge` 0.47.0 Migration Guide](getting-started/0-47-0-migration-guide.md)
 
 ---
 

docs/src/getting-started/0-47-0-migration-guide.md

@@ -0,0 +1,56 @@
+# `snforge` 0.47.0 Migration Guide
+
+Starting from version 0.47.0, `snforge` will by default support Scarb versions 2.12 or newer.
+This is due to the migration to the Scarb V2 version of procedural macros, which are used to handle arguments like `#[test]`
+in `snforge`.
+Thanks to this migration, tools like the Cairo plugin for VSCode will start showing better, more descriptive
+errors.
+
+To continue using `snforge` you will need to perform different actions depending on your Scarb version.
+
+## Scarb Versions >= 2.12.0
+
+For Scarb versions >= 2.12.0, we recommend upgrading your `snforge_std` dependency to the one matching your `snforge`
+installation (0.47.0 at the time of writing of this doc).
+
+In your `Scarb.toml` file, update the dependency.
+
+```toml
+[dev-dependencies]
+snforge_std = "0.47.0"
+```
+
+No further action is required.
+
+## Scarb Versions < 2.12.0
+
+> 📝 **Note**
+>
+> We recommend upgrading to at least Scarb 2.12.0, as steps outlined below will stop being supported soon.
+
+For Scarb versions < 2.12.0 it is still possible to continue using the latest `snforge`.
+We now publish a new package `snforge_std_compatibility`, supporting versions < 2.12.0.
+
+> 📝 **Note**
+>
+> `snforge_std_compatibility` may not provide full functionality in comparison to `snforge_std`.
+
+First, in your `Scarb.toml`, remove the `snforge_std` dependency and add `snforge_std_compatibility`.
+
+```diff
+[dev-dependencies]
+- snforge_std = "0.46.0"
++ snforge_std_compatibility = "0.47.0"
+```
+
+Next, replace all kinds of imports in your code from `snforge_std` to `snforge_std_compatibility`
+
+```diff
+// Replace use statements
+- use snforge_std::{ContractClassTrait, start_cheat_caller_address};
++ use snforge_std_compatibility::{ContractClassTrait, start_cheat_caller_address};
+
+// Replace full path usages
+- let result = snforge_std::declare("MyContract").unwrap();
++ let result = snforge_std_compatibility::declare("MyContract").unwrap();
+```

docs/theme/header.hbs

@@ -0,0 +1,27 @@
+<div class="migration-banner">
+    <p>
+        <strong>Important:</strong> If you're upgrading snforge to version 0.47.0 or later, please read the
+        <a href="{{ path_to_root }}getting-started/0-47-0-migration-guide.html">0.47.0 Migration Guide</a>.
+    </p>
+</div>
+
+<style>
+    .migration-banner {
+        position: relative;
+        z-index: 100;
+        background-color: #f8d7da;
+        color: #721c24;
+        border: 0.0625rem solid #f5c6cb;
+        border-radius: 0;
+        text-align: center;
+        padding: 5rem 1rem 0 1rem;
+        width: calc(100% + 8px + var(--page-padding));
+        margin-left: calc((8px + var(--page-padding)) * -1);
+    }
+
+    .migration-banner a {
+        color: #721c24;
+        font-weight: bold;
+        text-decoration: underline;
+    }
+</style>