Information needed about Best Practices / Guidelines / Backward Compatibility Promise

[ilnytskyi]

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

A guideline and best practices needed to for developers.
Currently we see the v2 release that introduced

• new folder structure
• a lot BC breaks and cool new features
• limited support of plugins with unclear future state

As a developer or merchant I'd like to have a highly flexible and customizable commerce system.
The modules and modules-links approach in v2 seems great at this point.
But it's unclear how deep can we go with customizations.
I might want to do things like I got used to do in other systems:

• install a 3rd party plugin and customize it according to my needs
• decorate / extend some core services
• replace some dependency via DI in particular place with my own dependency
• use core services / interfaces to build custom thing
• a lot other things.

At this point documentation does not provide clear list of what's recommended and what's not, except occasionally mentioning limitations like this page: https://docs.medusajs.com/learn/advanced-development/admin/constraints

So, as a developer, I am not sure about how safe do develop different thing now.
I don't know if calsses, modules, methods are deprecated I will likely know it after upgrade when something will break or stop working.

How can this issue be resolved?

1. introduce guidelines and best practices for medusajs developers
2. introduce some kind of annotations in codebase.
   I came from Magento, and it offers something like @api @deprecated tags https://developer.adobe.com/commerce/php/development/components/service-contracts/#using-the-api-tag as form of backward compatibility promise.
   This way I know if it's safe to use some core service in userland code.
   When something marker as @deprecated I can avoid using it.
3. Introduce DI usage best practices.
   In systems like symfony / magento we can do almost anything with dependency injection, one can expect doing same thing with medusa, however, now it's unclear if some service will be renamed or function / method signature changed or service dependencies changed. We will only know this during upgrade process. Additionally for plugins provider this may introduce a need to use various workarounds to ensure different medusa versions compatibility or even maintaining a few packages for this reason.
   ...

Are you interested in working on this issue?

• I would like to fix this issue

[shahednasser]

Thank you for your feedback! We're continuously working on improving our documentation and providing clarity on how Medusa's different concepts help you achieve your customizations, so this feedback is helpful and we'll take it into consideration.

We can look into introducing a documentation page on best practices, but regarding your other points:

introduce some kind of annotations in codebase.

We are gradually adopting TSDocs in the codebase, so if we deprecate something, you'll find an @deprecated tag in there.

now it's unclear if some service will be renamed or function / method signature changed or service dependencies changed. We will only know this during upgrade process.

For every update we put out release notes here on GitHub (see example), and we include in it any changes you should be aware of. So, you should always refer to the release notes before updating (will look into best ways to mention this in the documentation as well)

Dependency injection in Medusa is different than what you're used to with DI in Magento, so I recommend checking out this documentation for a clearer idea of how you'll use it: https://docs.medusajs.com/learn/basics/medusa-container

We also have the customization chapters that provide a realistic example and how to build it with Medusa. This should give you a better idea how to integrate third-party service, extend routes, etc…

[ilnytskyi]

Thanks for reply :)

I would like to highlight importance of upgrades policies and backward compatibility promises one more time.

For every update we put out release notes here on GitHub (see example), and we include in it any changes you should be aware of. So, you should always refer to the release notes before updating (will look into best ways to mention this in the documentation as well)

In provided example we see release notes of version 2.0.5, that looks like minor version, but it introduced significant BC break. The table is removed.

As a merchant or extension developer I would like to have more smooth and stable upgrades. In case anyone could have been affected by removed table we have not that many choices left.

1. Stay on prior version before making needed changes to upgrade. Because any customization around removed table need to be reworked.
2. As a module / plugin vendor - we need to maintain a few packages.

Possible solutions could be

1. Deprecate current gallery module and introduce new one.
2. Deprecate and remove later any service related to table to give merchants more time to upgrade.
3. Give the developers warning to not rely on core tables of certain area (in this example relations to images)