Write the Contract Upgrade Runbook

[codebestia]

Write the operational procedure for upgrading a deployed shade contract — the highest-risk routine operation the team performs — covering pre-flight verification, execution, and rollback.

Proposed steps:

• Create docs/operations/upgrade-runbook.md.
• Document pre-flight checks: storage compatibility review against the upgradeability rules, full test suite green, testnet rehearsal against a copy of production state, and reviewed diff of the interface.
• Document the execution sequence: pause the contract, install the new WASM, record the new hash, call upgrade, verify the new build, unpause.
• Document verification after upgrade: read a known invoice, merchant, and fee configuration; confirm analytics counters; run the deployment smoke test.
• Document rollback: reinstalling the previous WASM hash, and the cases where rollback is impossible (state written in a new format), with mitigations.
• Document a communication plan for merchants and integrators around the pause window.
• Include a sign-off checklist with named roles for approval.

Acceptance criteria:

• docs/operations/upgrade-runbook.md exists.
• Pre-flight, execution, verification, and rollback steps are all documented.
• Cases where rollback is impossible are called out explicitly.
• A sign-off checklist and merchant communication plan are included.

[achebejohnpaul]

Am a full-Stack Engineer focused on frontend, backend, APIs, automation, and modern web technologies. Passionate about solving real-world problems, contributing to open source, and delivering clean, scalable, review-ready solutions.

[samueldoo]

Hello Maintainer, I’d love to take ownership of this issue and submit a high-quality pull request once completed.