Add guide on upgradeability patterns in Move

[nwakaku]

Cedra Builders Forge - Submission

Season 1

📋 Task Information

Task Title: Upgradeability Patterns in Move #64

Issue Link: #64

Telegram: @Wizzy2304

---

✅ Checklist

• Commented "I'm taking this task" on the issue before starting
• This PR contains ONE task only
• All work is original (no copy-paste)
• Code compiles without errors and all tests pass
• Includes README, tests, and documentation
• Will share PR in Cedra Builders Telegram

---

📝 What Was Built

Created a guide on upgradeability patterns in Move for Cedra. It covers:

• Module upgrade strategies: three approaches (new module name, new account address, wrapper pattern) to handle module immutability
• Data migration patterns: forward-compatible storage design and explicit migration functions
• Version management: semantic versioning (SemVer) and version tracking in contract state
• Breaking vs non-breaking changes: guidelines with examples

The guide includes Move code examples, best practices, and common pitfalls. It helps developers plan and execute module upgrades on Cedra.

Task Issue

[Link to task issue - ]

Testing Instructions

1. Review the guide:

   cat docs/guides/upgradeability-patterns.md

2. Verify Move code examples:

   • Ensure examples use correct Move syntax
   • Check that upgrade strategies are properly demonstrated
   • Verify migration function patterns are complete

3. Test with a real contract (optional):

   # Create a test module following the patterns
   cd your-project/contract
   
   # Test version 1
   cedra move compile --named-addresses MyModule=default
   
   # Test version 2 with migration
   cedra move compile --named-addresses MyModuleV2=default

4. Validate markdown formatting:

   • Check that code blocks render correctly
   • Verify links to external resources work
   • Ensure the guide is readable and well-structured

5. Cross-reference with module publishing:

   • Compare with module-publishing.md for consistency
   • Verify versioning strategies align with actual publishing workflow

Dependencies or Setup Required

• None. The guide is documentation only and requires no additional setup.
• For testing code examples:
  • Cedra CLI installed
  • Access to Cedra testnet or mainnet
  • Cedra Framework dependencies in Move.toml
  • A Move development environment for compiling contracts
  • Understanding of module publishing (see Module Publishing Guide)

The guide is ready for review and can be merged into the upgradeability-patterns branch.