From 7119665dc92a2b65a6192469ed1af4a0c2e612aa Mon Sep 17 00:00:00 2001
From: Valeri Karpov <val@karpov.io>
Date: Mon, 3 Sep 2018 13:07:31 -0400
Subject: [PATCH] docs(deprecations): add detail about findAndModify
 deprecation re: #6922

---
 docs/deprecations.jade | 43 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 39 insertions(+), 4 deletions(-)

diff --git a/docs/deprecations.jade b/docs/deprecations.jade
index 2a0d06b1a48..1adf392a292 100644
--- a/docs/deprecations.jade
+++ b/docs/deprecations.jade
@@ -36,15 +36,15 @@ block content
     The MongoDB Node.js driver rewrote the tool it uses to parse [MongoDB connection strings](https://docs.mongodb.com/manual/reference/connection-string/).
     Because this is such a big change, they put the new connection string parser
     behind a flag. To turn on this option, pass the `useNewUrlParser` option to
-    [`mongoose.connect()`](https://mongoosejs.com/docs/api.html#mongoose_Mongoose-connect)
-    or [`mongoose.createConnection()`](https://mongoosejs.com/docs/api.html#mongoose_Mongoose-createConnection).
+    [`mongoose.connect()`](/docs/api.html#mongoose_Mongoose-connect)
+    or [`mongoose.createConnection()`](/docs/api.html#mongoose_Mongoose-createConnection).
 
     ```javascript
     mongoose.connect(uri, { useNewUrlParser: true });
     mongoose.createConnection(uri, { useNewUrlParser: true });
     ```
 
-    You can also [set the global `useNewUrlParser` option](https://mongoosejs.com/docs/api.html#mongoose_Mongoose-set)
+    You can also [set the global `useNewUrlParser` option](/docs/api.html#mongoose_Mongoose-set)
     to turn on `useNewUrlParser` for every connection by default.
 
     ```javascript
@@ -56,4 +56,39 @@ block content
     To test your app with `{ useNewUrlParser: true }`, you only need to check
     whether your app successfully connects. Once Mongoose has successfully
     connected, the URL parser is no longer important. If you can't connect
-    with `{ useNewUrlParser: true }`, please [open an issue on GitHub](https://github.com/Automattic/mongoose/issues/new).
\ No newline at end of file
+    with `{ useNewUrlParser: true }`, please [open an issue on GitHub](https://github.com/Automattic/mongoose/issues/new).
+
+    ## `findAndModify()`
+
+    If you use [`Model.findOneAndUpdate()`](/docs/api.html#model_Model.findOneAndUpdate),
+    by default you'll see the below deprecation warning.
+
+    ```
+    DeprecationWarning: collection.findAndModify is deprecated. Use findOneAndUpdate, findOneAndReplace or findOneAndDelete instead.
+    ```
+
+    Mongoose's `findOneAndUpdate()` long pre-dates the MongoDB driver's `findOneAndUpdate()`
+    function, so it uses the MongoDB driver's [`findAndModify()` function](http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#findAndModify)
+    instead. You can opt in to using using the MongoDB driver's `findOneAndUpdate()`
+    function using the [`useFindAndModify` global option](/docs/api.html#mongoose_Mongoose-set).
+
+    ```javascript
+    // Make Mongoose use `findOneAndUpdate()`. Note that this option is `true`
+    // by default, you need to set it to false.
+    mongoose.set('useFindAndModify', false);
+    ```
+
+    This option affects the following model and query functions. There are
+    no intentional backwards breaking changes, so you should be able to turn
+    this option on without any code changes. If you discover any issues,
+    please [open an issue on GitHub](https://github.com/Automattic/mongoose/issues/new).
+
+    * [`Model.findByIdAndDelete()`](/docs/api.html#model_Model.findByIdAndDelete)
+    * [`Model.findByIdAndRemove()`](/docs/api.html#model_Model.findByIdAndRemove)
+    * [`Model.findByIdAndUpdate()`](/docs/api.html#model_Model.findByIdAndUpdate)
+    * [`Model.findOneAndDelete()`](/docs/api.html#model_Model.findOneAndDelete)
+    * [`Model.findOneAndRemove()`](/docs/api.html#model_Model.findOneAndRemove)
+    * [`Model.findOneAndUpdate()`](/docs/api.html#model_Model.findOneAndUpdate)
+    * [`Query.findOneAndDelete()`](/docs/api.html#query_Query-findOneAndDelete)
+    * [`Query.findOneAndRemove()`](/docs/api.html#query_Query-findOneAndRemove)
+    * [`Query.findOneAndUpdate()`](/docs/api.html#query_Query-findOneAndUpdate)
\ No newline at end of file