Confusing error messages for deprecated

[FrancisVila]

I get the following deprecated error:

  (node:10816) DeprecationWarning: Mongoose: `findOneAndUpdate()` and `findOneAndDelete()` without the `useFindAndModify` option set to false are deprecated. See: https://mongoosejs.com/docs/deprecations.html#findandmodify

What I would expect:

• for the error message to tell me which commands to use, rather than suggesting setting an option to false. I imagine the people who decided to deprecate a command had reasons to do so; I'm starting out using this technology and I'd like to know how I'm supposed to use it. Setting an option to false sounds like sweeping the issue under the carpet.
• the linked page does not clearly state what is deprecated and what is supposed to be the replacement

[vkarpov15]

The way to work around this issue is to add:

// Make Mongoose use `findOneAndUpdate()`. Note that this option is `true`
// by default, you need to set it to false.
mongoose.set('useFindAndModify', false);

Admittedly this is a case of sweeping an issue under the carpet: Mongoose's findOneAndUpdate() method was originally written as a helper that uses findAndModify() under the hood, but then the MongoDB driver introduced its own findOneAndUpdate() function, so we're trying to transition to using their findOneAndUpdate() while minimizing the risk of breaking changes. Sorry for the inconvenience and thanks for your patience 👍

[FrancisVila]

I would add in a phrase in the doc, such as (after the DeprecationWarnings) :

If you are using this command for the first time in this version, you can either:

• ignore this warning - it should disappear once the new syntax becomes the default
• set 'useFindAndModify' to false, as suggested