From dead67c0eccb417eaece4df2cc4f58cd32d0754b Mon Sep 17 00:00:00 2001 From: Jacques-codes Date: Mon, 1 Jun 2026 19:47:06 +0200 Subject: [PATCH] feat: ocs/upgrade-classes.md lists upgrade classes (Safe / Caution / Breaking) --- Readme.md | 8 +++--- docs/cli-command-groups.md | 2 +- docs/index.md | 1 + docs/issues/backlog-100-issues.md | 2 +- docs/issues/roadmap-priorities.md | 2 +- docs/tutorials/upgrade-review.md | 9 ++++--- docs/upgrade-classes.md | 45 ++++++++++++++++++++++++------- 7 files changed, 49 insertions(+), 20 deletions(-) diff --git a/Readme.md b/Readme.md index db034473..d1b29940 100644 --- a/Readme.md +++ b/Readme.md @@ -260,9 +260,11 @@ soroban-debug upgrade-check --old current.wasm --new upgraded.wasm ``` The debugger runs parallel traces and classifies the upgrade: -- **Safe:** No breaking changes, stable inputs execution. -- **Caution:** Non-breaking changes like new map arguments or endpoints. -- **Breaking:** Removed functions, changed signatures, or execution panic regressions. +- **Safe:** The exported surface is unchanged, and sampled execution matches. +- **Caution:** New exported functions were added without changing existing signatures. +- **Breaking:** Functions were removed, signatures changed, or sampled execution diverged. + +See [docs/upgrade-classes.md](docs/upgrade-classes.md) for the full mapping between contract changes and upgrade classes. ### Completions Command diff --git a/docs/cli-command-groups.md b/docs/cli-command-groups.md index 4e043757..eb9cd4f5 100644 --- a/docs/cli-command-groups.md +++ b/docs/cli-command-groups.md @@ -18,7 +18,7 @@ Commands used for executing contract functions and interactive troubleshooting. Commands for static analysis, profiling, and version comparisons. - **`inspect`**: View contract metadata, exported functions, and DWARF source mappings without executing code. -- **`upgrade-check`**: Compares two WASM files to identify breaking API changes or storage layout shifts. +- **`upgrade-check`**: Compares two WASM files and reports upgrade classes based on exported function compatibility and optional execution diffs. See [Upgrade Classes](upgrade-classes.md) for the exact mapping. - **`optimize`**: Provides automated suggestions for reducing gas (CPU/memory) consumption. - **`profile`**: Identifies performance hotspots and budget-heavy instruction sequences. - **`compare`**: Renders a side-by-side diff of two execution traces to catch regressions. diff --git a/docs/index.md b/docs/index.md index d57b6e9a..884b993b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,6 +29,7 @@ Welcome to the Soroban Debugger documentation. This index helps you navigate the ## 🎓 Tutorials - [Debugging Auth Errors](tutorials/debug-auth-errors.md) — Diagnosing `require_auth()` failures. - [Scenario Runner Cookbook](tutorials/scenario-runner.md) — Writing automated integration tests. +- [Upgrade Review](tutorials/upgrade-review.md) — Interpreting `upgrade-check` output and upgrade classes. - [Plugin Development Tutorial](tutorials/plugin-development.md) — Build, install, and iterate on a plugin end-to-end. - [Symbolic Analysis Budgets](tutorials/symbolic-analysis-budgets.md) — Configuring symbolic exploration. - [Understanding Budget Trends](tutorials/understanding-budget.md) — Visualizing resource usage. diff --git a/docs/issues/backlog-100-issues.md b/docs/issues/backlog-100-issues.md index 7bf0ad20..e7b37d28 100644 --- a/docs/issues/backlog-100-issues.md +++ b/docs/issues/backlog-100-issues.md @@ -83,7 +83,7 @@ Roadmap view: [Section C priorities](roadmap-priorities.md#section-c--feature-re - **I-031** `[DOC]` `docs/wasm-artifact-metadata.md` (1716 bytes) documents the metadata fields but doesn't show an example `inspect --format json` output that contains them. - **I-032** `[DOC]` `docs/watch-mode.md` (744 bytes) mentions the watch command but doesn't document the polling interval, file-glob support, or debounce behavior. - **I-033** `[DOC]` `docs/storage-snapshot.md` (1761 bytes) references `--import-storage` but the feature matrix shows this is `PARTIAL` in the extension (use `snapshotPath` instead) — the doc doesn't mention the distinction. -- **I-034** `[DOC]` `docs/upgrade-classes.md` (1071 bytes) lists upgrade classes (Safe / Caution / Breaking) but doesn't explain what contract changes map to each class. +- ~**I-034** `[DOC]` `docs/upgrade-classes.md` (1071 bytes) lists upgrade classes (Safe / Caution / Breaking) but doesn't explain what contract changes map to each class.~ - **I-035** `[DOC]` `docs/batch-execution.md` references JSON format but doesn't document the full set of batch result fields (e.g., `duration_ms`, `error`) that appear in JSON output mode. - **I-036** `[DOC]` `docs/optimization-guide.md` (16 KB) is the longest doc in the set and has no internal TOC. - **I-037** `[DOC]` `docs/source-level-debugging.md` (3393 bytes) mentions DWARF but doesn't explain what happens when DWARF info is absent (heuristic fallback) — covered in the FAQ but not here. diff --git a/docs/issues/roadmap-priorities.md b/docs/issues/roadmap-priorities.md index 54604314..42879955 100644 --- a/docs/issues/roadmap-priorities.md +++ b/docs/issues/roadmap-priorities.md @@ -91,7 +91,7 @@ useful order instead of re-triaging the whole epic every time. | I-031 | Add `inspect --format json` example output to `wasm-artifact-metadata.md` | P2 | S | Docs | — | 2 | | I-032 | Expand `docs/watch-mode.md` with polling interval and debounce details | P2 | S | Docs | — | 2 | | I-033 | Clarify CLI vs. extension behavior in `docs/storage-snapshot.md` | P1 | S | Docs | — | 2 | -| I-034 | Map contract change types to upgrade classes in `upgrade-classes.md` | P1 | M | Docs | — | 2 | +| ~I-034~ | ~Map contract change types to upgrade classes in `upgrade-classes.md`~ | P1 | M | Docs | — | 2 | | I-035 | Document full batch result JSON fields in `docs/batch-execution.md` | P2 | S | Docs | — | 2 | | I-036 | Add internal TOC to `docs/optimization-guide.md` | P2 | XS | Docs | — | 2 | | I-037 | Add DWARF-absent heuristic fallback to `source-level-debugging.md` | P1 | S | Docs | — | 2 | diff --git a/docs/tutorials/upgrade-review.md b/docs/tutorials/upgrade-review.md index d6e5a26b..e46ce62b 100644 --- a/docs/tutorials/upgrade-review.md +++ b/docs/tutorials/upgrade-review.md @@ -16,7 +16,8 @@ soroban-debug upgrade-check --old old.wasm --new new.wasm ``` ## Step 3: Interpret the results -The tool classifies the upgrade into one of three categories: -- **Safe:** No exported functions were removed, and signatures match. -- **Caution:** Non-breaking additions (like new functions) were found. -- **Breaking:** Functions were removed, or arguments changed in incompatible ways. \ No newline at end of file +The tool classifies the upgrade into one of three categories. For the full mapping between contract changes and classes, see [Upgrade Classes](../upgrade-classes.md). + +- **Safe:** The exported surface is unchanged, and any sampled `--test-inputs` executions match. +- **Caution:** New exported functions were added, but existing signatures still match. +- **Breaking:** Functions were removed, signatures changed, or a sampled execution produced a different result. diff --git a/docs/upgrade-classes.md b/docs/upgrade-classes.md index f25fe5b2..e375966f 100644 --- a/docs/upgrade-classes.md +++ b/docs/upgrade-classes.md @@ -1,15 +1,40 @@ # Upgrade Compatibility Classes -When using the `soroban-debug upgrade-check` command, the debugger runs deep analysis between the old and new WASM binaries. Instead of a binary valid/invalid report, it classifies the upgrade into three categories to help operators manage release risk. +When you run `soroban-debug upgrade-check`, the debugger compares the old and new WASM binaries and classifies the result based on exported function compatibility and, when provided, test-input execution diffs. -## 🟢 Safe -- **Criteria:** No parameter signature changes, no removed functions, and identical behavior in test payloads. -- **Risk:** Minimal. Can be executed without breaking downstream callers. +The current analyzer uses a simple decision rule: -## 🟡 Caution -- **Criteria:** Contains only non-breaking changes, like new functions or increased storage mappings without altering existing contract invariants. -- **Risk:** Changes the surface area and expands interface footprint, so downstream indexers or dapps must be aware if they upgrade. +- Any removed or signature-changed exported function is `Breaking`. +- Any execution mismatch from `--test-inputs` is `Breaking`. +- If there are no breaking changes but there is at least one added exported function, the result is `Caution`. +- If the exported surface and sampled execution are unchanged, the result is `Safe`. -## 🔴 Breaking -- **Criteria:** Changing function parameters, dropping functions, return type mutation, or execution differences meaning outputs would wildly differ. -- **Risk:** High. Calling systems will fail if they don't adapt immediately to the API surface change. +## Safe +Use `Safe` when the contract change is effectively identical from the debugger's point of view: + +- No exported functions were added. +- No exported functions were removed. +- No exported function signatures changed. +- No sampled executions differed when `--test-inputs` was used. + +This means downstream callers can keep using the same contract interface without code changes. + +## Caution +Use `Caution` when the upgrade is additive but still worth a review: + +- One or more exported functions were added. +- Existing exported function names, parameter counts, parameter types, and return types stayed the same. +- No sampled executions differed when `--test-inputs` was used. + +This class means the contract grew a new surface area, so callers and indexers may want to notice the new entry points even though the upgrade is still compatible. + +## Breaking +Use `Breaking` when the upgrade changes how existing callers interact with the contract: + +- An exported function was removed. +- An exported function's parameter count changed. +- An exported function's parameter types changed. +- An exported function's return types changed. +- A sampled execution produced a different result with `--test-inputs`. + +This class means the old and new contract versions are not safely interchangeable without updating callers or reviewing the changed behavior.