Context

Some users have complained about changes between Go Driver v1 and v2 unmarshal behavior that don't cause compilation errors but can cause runtime errors or even subtle bugs (e.g. GODRIVER-3689, GODRIVER-3576). Something we can do to make migration easier is to provide a set of BSONOptions that closely approximates the v1 unmarshal behavior (inspired by the Go JSON [DefaultOptionsV1](https://pkg.go.dev/encoding/json/internal/jsonopts#pkg-variables) options type).

Note that it's not currently possible to closely approximate the v1 decode behavior. A known feature that must be implemented is GODRIVER-3746. We may need to implement additional features to get close enough to v1 unmarshal behavior.

Definition of Done

• Discover all marshal/unmarshal behavior changes between v1 and v2.
  • Currently the most significant known difference is the default unmarshal type (see GODRIVER-3746).
• Define an options.BSONOptions value in the mongo/options package that sets the unmarshal behavior to the closest approximation to Go Driver v1 behavior. E.g.

  var V1BSONOptions = BSONOptions{
  	InferDocumentType: true, // TODO: Requires GODRIVER-3746.
  }
  

Pitfalls

• It may not be possible to get close enough to v1 unmarshal behavior for it to make sense to define a v1-compatibility value.
• This approach only handles configuring a mongo.Client's unmarshal behavior. There isn't a great way to do the same for bson.Decoder.