Add error raise for deep_symbolize_keys!

[IvanTakarlikov-st]

Overview

Analogue of this PR but for `.deep_symbolize_keys!'

Inspired by few hours debugging why things behave weird

[DEVELOPMENT] tags/master-build-29117^0 irb(main):001:0> d = BSON::Document.new(foo: 'bar')
=> {"foo"=>"bar"}
[DEVELOPMENT] tags/master-build-29117^0 irb(main):002:0> d.deep_symbolize_keys!
=> {"foo"=>"bar"}
[DEVELOPMENT] tags/master-build-29117^0 irb(main):003:0> d.symbolize_keys!
(irb):3:in `<main>': symbolize_keys! is not supported on BSON::Document instances. Please convert the document to hash first (using #to_h), then call #symbolize_keys! on the Hash instance (ArgumentError)

It will be also great to backport it to 4 major, I can create PR if you'll accept this one.

[jamis]

Great catch, @IvanTakarlikov-st , and thank you very much for the pull request.

Even though this is the right thing to do, it still represents a breaking change. Whether it was intentional or not, #deep_symbolize_keys! is currently a part of the public API. Per semantic versioning constraints, this change will need to be part of a new major version of the library (v6.0.0).

I propose the following:

1. Change this PR so it issues a deprecation warning if BSON::Document#deep_symbolize_keys! is called.
2. Create a ticket in Jira that will raise the error as you've done here, as part of an eventual ruby-bson 6.0.0 release.

I can create the Jira ticket, if you'll adjust this PR to warn instead of raise.

[IvanTakarlikov-st]

Great catch, @IvanTakarlikov-st , and thank you very much for the pull request.

Even though this is the right thing to do, it still represents a breaking change. Whether it was intentional or not, #deep_symbolize_keys! is currently a part of the public API. Per semantic versioning constraints, this change will need to be part of a new major version of the library (v6.0.0).

I propose the following:

1. Change this PR so it issues a deprecation warning if BSON::Document#deep_symbolize_keys! is called.
2. Create a ticket in Jira that will raise the error as you've done here, as part of an eventual ruby-bson 6.0.0 release.

I can create the Jira ticket, if you'll adjust this PR to warn instead of raise.

It makes a total sense to me, I'll adjust it to be warning.

[jamis]

JIRA ticket here: https://jira.mongodb.org/browse/RUBY-3656

[IvanTakarlikov-st]

Updated the behaviour to print warn, not raising error.

[johnnyshields]

@jamis a hard error is much better than a warning here. My team was using this by accident, and I guarantee they will miss any warning line.

A hard error would have saved us from a production issue. Data corruption -- which the current broken method causes, and a warning does not fix -- is far worse than just getting an error which you can see and fix. How about releasing it as BSON 5.1, as users will read the release notes.

This is one of the many issues I fixed in #348. @IvanTakarlikov-st please take a look at that PR, if you're using BSON::Document beware there are many other similarly broken behaviors.

[jamis]

@johnnyshields I agree, and said as much in my comments to Ivan. However, as I said above, raising an exception is a breaking change, and can't be introduced until BSON 6. In the meantime, an error message will have to suffice.

[johnnyshields]

OK, well, we can agree to disagree on the definition of "breaking change". In my view, you can't break something that's already broken--in fact, you do your users a service by clearly flagging it as such!