Add documentation on updating Medusa

[puppycodes]

What Medusa version and documentation are you using?

v2

Preliminary Checks

• This issue is not a duplicate. Before opening a new issue, please search existing issues: https://github.com/medusajs/medusa/issues

Issue Summary

Something missing from the V2 docs are upgrades for minor versions of Medusa like 2.1 to 2.2. Appreciate the detailed release notes of each version but it could be great to extract these from Github and put those more formally in the docs.

How can this issue be resolved?

1. Add a placeholder for version upgrades in the main documentation menu
2. Add a general instruction for yarn upgrade commands and anything general
3. Point users to the release notes or extract them to the docs
4. Communicate the logic around breaking changes and when to expect backwards compatibility.

Are you interested in working on this issue?

• I would like to fix this issue

[puppycodes]

also thank you for keeping Medusa open source and all the work you do <3

[shahednasser]

Thank you for the feedback. Is there a reason you feel like it needs to also be in the documentation?

In the docs we show the current version in the navigation bar and when you click on it, it will take you to the version's release notes. We appreciate more details on why you find this necessary.

[puppycodes]

The documentation is great so far but upgrades are an integral part of the development cycle and can be daunting. I first go to the upgrade documentation to learn about any global project idiosyncrasies before looking for more specific version information. Even if its a product decision for Medusa not to focus on global update docs it's good to state that so we don't end up digging around.

Explicit backwards compatibility strategies create confidence in the platform and most importantly if a serious vulnerability is discovered you want to be able to quickly patch within the same major version. If you have to work your way through other changes this costs time and introduces exponential complexity with heavily customized stores.

[shahednasser]

Thank you for the details. I think there's a great point of at least adding a page covering where you can find the upgrade guides and how to use the release notes. We do mention it in the installation guide but seems like it's not discoverable enough.

At the moment there's no plan of extracting the release notes, but we should start with the upgrade guide page and see whether more is necessary. Thanks again!