docs: Add upgrade report link in README (#305)

Author: zguesmi

.github/workflows/upgrade-facets.yml

@@ -1,5 +1,6 @@
-# This is a template workflow for upgrading PoCo facets.
-# Update the script path (UPGRADE_SCRIPT environment variable) for each specific upgrade.
+# This is a generic workflow that should be used to upgrade PoCo facets.
+# Change the environment variable `UPGRADE_SCRIPT` to point to the correct
+# script for each specific upgrade.
 
 name: Upgrade PoCo Facets
 
@@ -16,7 +17,7 @@ on:
         default: 'arbitrumSepolia'
       dry-run:
         description: 'Dry Run (fork test only, no actual deployment)'
-        required: false
+        required: true
         type: boolean
         default: true
 

docs/README.md

@@ -7,6 +7,10 @@
 
 The detailed API documentation for each Solidity contract — including their functions, events, and data structures — can be found [here](./solidity/index.md).
 
+## Upgrades
+
+Reports of all PoCo upgrades are available in [scripts/upgrades/](../scripts/upgrades/)
+
 ## Diagrams
 
 ### UML diagrams

scripts/upgrades/README.md

@@ -1,26 +1,30 @@
 # PoCo Smart Contracts Upgrade Guide
 
-This document explains the recommended steps for creating and applying a safe, traceable,
-and reproducible upgrade to the PoCo Diamond proxy.
+This document explains the recommended steps for creating and applying
+a safe, traceable, and reproducible upgrade to the PoCo Diamond proxy.
 
 ## Upgrade Steps
 
 0. **Ensure all tests pass**:<br>
     Run the full test suite to make sure everything is working before starting an upgrade.
 
 1. **Create a new upgrade script**:<br>
-    Name the script using the version and upgrade name in the form `vX.Y.Z-upgrade-name.ts`
-    and implement the upgrade logic.
+    Name the script using the version and upgrade name format `vX.Y.Z-upgrade-name.ts` and
+    implement the upgrade logic.
 
 2. **Create a corresponding Markdown report**:<br>
-    Copy the template file `v0.0.0-template.md` and rename it to match the script's name
-    (`vX.Y.Z-upgrade-name.md`).
+    Copy the template file `v0.0.0-template.md` and rename it to match the script file name.
+    The name should be of the form `vX.Y.Z-upgrade-name.md`.
 
 3. **Test dry-runs locally**:<br>
     Use the script [./dry-run.sh](./dry-run.sh) and check the logs.
 
 4. **Update GitHub Actions**:<br>
-    Modify `upgrade-facets.yml` workflow to call the new upgrade script.
+    Modify `upgrade-facets.yml` workflow to call the new upgrade script.<br>
+    Note: to run the upgrade script manually (for testing), use:
+    ```
+    npx hardhat run scripts/upgrades/vX.Y.Z-upgrade-name.ts --network <network>
+    ```
 
 5. **Upgrade on Testnet**:
    - ⚠️ Always upgrade on the testnet first.
@@ -38,4 +42,4 @@ and reproducible upgrade to the PoCo Diamond proxy.
     Fill in all required information in `vX.Y.Z-upgrade-name.ts` (tx hashes, logs, ...).
 
 8. **Create a release**
-   - Use **Release Please** to tag the upgrade version and create the release on GitHub.
+   - Use **Release Please** to tag the upgraded version and create the release on GitHub.