I've found this bug through an issue I'm having with Mongoid, so I'm not 100% sure if this is an issue with BSON, or that Mongoid is using it wrong.

Consider the following code:

attributes = BSON::Document.new
attributes["test"] = nil
(attributes["test"] ||= {}).merge!({"test" => "test})
# You'd expect attributes["test"] to be {"test" => "test"} 
# here, but it's actually {}

The last line is found in Mongoid here: https://github.com/mongodb/mongoid/blob/master/lib/mongoid/attributes.rb#L179 and (I think) is the result is causing issues like this: http://stackoverflow.com/questions/29899935/mongoid-localized-field-not-being-set-in-first-form-submission

It works fine if you make attributes a Hash instead, so I presume it's something the way ||= or merge! are implemented in BSON::Document?

Writing my example differently, e.g.

attributes = BSON::Document.new
attributes["test"] = nil
attributes["test"] ||= {}
attributes["test"].merge!({"test" => "test})

also works as expected.