Merge pull request #12685 from Automattic/vkarpov15/gh-11990

docs(document): explain that `$isNew` is `false` in post('save') hooks

lib/document.js

@@ -220,6 +220,17 @@ function Document(obj, fields, skipId, options) {
  *     const user = await User.findOne({ name: 'John Smith' });
  *     user.$isNew; // false
  *
+ * Mongoose sets `$isNew` to `false` immediately after `save()` succeeds.
+ * That means Mongoose sets `$isNew` to false **before** `post('save')` hooks run.
+ * In `post('save')` hooks, `$isNew` will be `false` if `save()` succeeded.
+ *
+ * #### Example:
+ *
+ *     userSchema.post('save', function() {
+ *       this.$isNew; // false
+ *     });
+ *     await User.create({ name: 'John Smith' });
+ *
  * For subdocuments, `$isNew` is true if either the parent has `$isNew` set,
  * or if you create a new subdocument.
  *