As progress is made maintaining backwards compatibility makes APIs grow more complicated and some default behaviors become non-intuitive.

One example is that update() by default only operates on a single document without the optional "multi" argument telling it to do otherwise.
This is counter intuitive to anyone coming from SQL as well as inconsistent with other API calls such as find() which returns all matches without an additional limit() modifier.

Breaking backwards compatibility is generally bad, but becomes necessary in order to improve the API and keep it intuitive and clean moving forward.

I propose a mechanism that allows both to be achieved:

1) add server flags that allow specific API behavior selection
2) introduce a deprecation period, during which the default API behavior is the original (or most recent) behavior
3) after the deprecation period, change the default to the new behavior/API spec
4) attempts to use old behavior can become errors that return/raise exceptions, thus finding code that uses old behavior becomes a matter of normal debugging for those wishing to update code to the current API behavior. (This can obviously be done during the deprecation period by changing the default via the server flags. A catch-all flag could be added such as "API-version-X", "latest-API" or "new-features" such as MYSQL does to let people develop their code with a forward-looking mentality.)

Anyone that needs to maintain old behavior for old code can simply add the appropriate server flag switch.
A long enough deprecation period, or simply visible-enough (documentation-wise) exposition of such changes will suffice to not leave anyone confused.

This is really nothing new--many other projects do this or something very similar. I think mongodb will benefit from doing so as well.

With 1.6.0 just out and 1.7 starting, now might be a really good time to begin this.