Mongodb-odm: [RFC] [2.0] Drop YAML mapping driver

[alcaeus]

Similar to ORM, I'm very inclined to drop the YAML mapping driver for 2.0.

In applications, I'd recommend using annotations to map documents: the mapping is where the code lives, and since the code isn't designed to be extended there's no reason to be able to override the mapping.
For libraries that provide mappings to ODM, it has always been recommended to rely on XML mappings as it allows overriding and is also validated against the schema, which isn't the case for YAML.

Currently, the YAML driver only creates maintenance overhead, which I'd like to avoid: there are several changes coming up that will require work on the drivers (changing metadata objects, views in MongoDB, document validation, etc.) and I'd like to avoid as much of that as possible.

[redthor]

We don't use annotations because it creates an infrastructure dependency on our domain. We use yaml heavily. I din't feel like we gain much from XML schema validation and yaml has better DX IMO.

However I'm not maintaining doctrine so I'm not aware of the pain! We would just need to find a way to convert the forty files from yaml to XML if this goes ahead.

As always thanks for your work on this library :)

[alcaeus]

You raise fair points. Converting YML to XML mappings is (currently) a manual process, as we don't have an XML writer for mappings.

As always thanks for your work on this library :)

You're very welcome! 🍻

[malarzm]

How about deprecation in 2.0 and removal in 3.0? My reasoning is that we won't do mapping changes in 2.0 anyway and it'll be one thing less for users to take care of while updating.

[alcaeus]

We won't do mapping changes in 2.0, but new features in 2.x will require mapping changes. It's those changes I'd like to avoid doing.

[Majkl578]

We don't use annotations because it creates an infrastructure dependency on our domain.

Well, YAML is the identical burden you have there, it's only moved to a separate file and different tongue. If you ever decide to switch i.e. from ODM to ORM, you will have to rework your YAML mapping completely (if not domain design as well), same for annotations. Rule of thumb when deciding mapping driver should be: Is it my private application or a library (especially in case of OSS)? If the former, use annotations, if the latter, use XML (Symfony suggests XML too). At least that's what ORM will suggest. :)

it'll be one thing less for users to take care of while updating

And at the same time it becomes another burden - for you to maintain in 2.x and eventually for users anyway when they start upgrading to 3.0. ORM is undergoing huge metadata refactoring and at the same time drops YAML, code generators etc., it will be a lot to be careful about and eventually migrate during upgrade from 2.x to 3.0, some users might not be happy. I'd say: drop it, the sooner the better, if you don't really need it. 👍

[malarzm]

I agree with your points, we just settled some time ago that 2.0 will contain new driver and not much more so people can start using ODM with PHP 7 directly. The more stuff we remove now the more painful the upgrade will be. My currect (christmas so good and people oriented :D) thinking is that we could get 2.0 out the door and have 3.0 even 6 months after with more removals.

[alcaeus]

we just settled some time ago that 2.0 will contain new driver and not much more so people can start using ODM with PHP 7 directly.

Correct. The problem I see here is that keeping YAML around in 2.0 forces us to add all new features (of which there are a few) to the YAML driver as well, which I'd like to avoid.

One option would be to extract the YAML driver to a legacy package and mark it as unsupported: people could use that to ease the migration to 2.0 without having to change schema, but they'd have to migrate away from it if they want support. WDYT?

[redthor]

@Majkl578 thanks for your comments. I'd argue it's not a similar burden in our case. Our PHP app is broken into many packages, each of which has its own infrastructure layer. We can drop the ODM completely in one of our packages and we won't need to touch our domain code or any of our other packages. We just update the package Repositories and remove the YAML files.

Also if we need to make changes it's generally easier to find and parse YAML files rather than searching for relevant domain class files.

@alcaeus I love the idea of separate Mapping Driver packages, I actually came back to this discussion to say the same and then saw your comment. I was thinking something like:

doctrine/mongodb-odm recommends:

• doctrine/mongodb-odm-mapping-xml
• doctrine/mongodb-odm-mapping-yaml

Then the mongodb-odm-mapping-yaml one could be marked as deprecated OR get help from contributors to maintain it. Another alternative is that a developer could fork it so they can use some features but ignore others. Perhaps there might be a mongodb-odm-mapping-json at some point...

I have no idea of the effort involved in reconfiguring the code to support such a structure.

[alcaeus]

TBH, the extraction would only cover YAML with the sole intent of deprecating it or offloading it to someone else that cares more for it than we do. XML is the recommended format for your use case and for libraries (e.g. Symfony bundles) that share mapping data. For "basic" application we recommend annotations (with the exception of applications where people want to keep domains separate).

In your case, I suggest moving to XML to take advantage of validation, editor tools based on the schema and so on.

[malarzm]

All right, I'm on board with removing YAML driver, we'll provide a command to convert mappings: #1730

[redthor]

Thanks @malarzm - we'd be really happy to test this!

By the way, @alcaeus - just for reference, could you link the proposal to remove YAML from Doctrine ORM? I did a search in issues but I might have been looking in the wrong place.

[Majkl578]

https://github.com/doctrine/doctrine2/pull/5932

[redthor]

Oh, wow, I must have been sleeping under rock not to hear about that doctrine PR - it's been around July 2016!

(It might have been good if during that time there was a message at the top of YAML Driver docs saying that YAML might be removed?)

I'll see if I can get a PR up to add a deprecation warning to the MongoDB YAML driver documentation to alert anyone that is visiting.

[Majkl578]

(It might have been good if during that time there was a message at the top of YAML Driver docs saying that YAML might be removed?)

Can't speak for ODM, but ORM 2.7 will be deprecations-only release, prepping for 3.0, with polyfill/forward-compat where required. Some already decided ones are marked with Deprecation label.

[malarzm]

We plan to do same thing with 1.3 release