Merge pull request #13251 from Automattic/vkarpov15/gh-13193

docs: add version support and check version docs

docs/check-version.md

@@ -0,0 +1,34 @@
+# How to Check Your Mongoose Version
+
+To check what version of Mongoose you are using in Node.js, print out the [`mongoose.version` property](./api/mongoose.html#Mongoose.prototype.version) as follows.
+
+```javascript
+const mongoose = require('mongoose');
+
+console.log(mongoose.version); // '7.x.x'
+```
+
+We recommend printing the Mongoose version from Node.js, because that better handles cases where you have multiple versions of Mongoose installed.
+You can also execute the above logic from your terminal using Node.js' `-e` flag as follows.
+
+```
+# Prints current Mongoose version, e.g. 7.0.3
+node -e "console.log(require('mongoose').version)"
+```
+
+## Using `npm list`
+
+You can also [get the installed version of the Mongoose npm package](https://masteringjs.io/tutorials/npm/version) using `npm list`.
+
+```
+$ npm list mongoose
+test@ /path/to/test
+└── mongoose@7.0.3 
+```
+
+`npm list` is helpful because it can identify if you have multiple versions of Mongoose installed.
+
+Other package managers also support similar functions:
+
+- [`yarn list --pattern "mongoose"`](https://classic.yarnpkg.com/lang/en/docs/cli/list/)
+- [`pnpm list "mongoose"`](https://pnpm.io/cli/list)

docs/guides.md

@@ -42,6 +42,10 @@ integrating Mongoose with external tools and frameworks.
 * [Testing with Jest](jest.html)
 * [SSL Connections](tutorials/ssl.html)
 
+## Other Guides
+
+* [How to Check Your Mongoose Version](check-version.html)
+
 ## Migration Guides
 
 * [Mongoose 5.x to 6.x](migrating_to_6.html)

docs/layout.pug

@@ -143,6 +143,8 @@ html(lang='en')
                 a.pure-menu-link(href="/docs/6.x/docs/migrating_to_6.html", class=outputUrl === '/docs/6.x/docs/migrating_to_6.html' ? 'selected' : '') Migration Guide
               li.pure-menu-item
                 a.pure-menu-link(href="/docs/6.x/docs/compatibility.html", class=outputUrl === '/docs/6.x/docs/compatibility.html' ? 'selected' : '') Version Compatibility
+              li.pure-menu-item
+                a.pure-menu-link(href="/docs/6.x/docs/version-support.html", class=outputUrl === '/docs/6.x/docs/version-support.html' ? 'selected' : '') Version Support
               li.pure-menu-item
                 a.pure-menu-link(href="/docs/6.x/docs/faq.html", class=outputUrl === '/docs/6.x/docs/faq.html' ? 'selected' : '') FAQ
               li.pure-menu-item

docs/migrating_to_5.md

@@ -1,5 +1,8 @@
 # Migrating from 4.x to 5.x
 
+Please note: we plan to discontinue Mongoose 5 support on March 1, 2024.
+Please see our [version support guide](./version-support.html).
+
 There are several [backwards-breaking changes](https://github.com/Automattic/mongoose/blob/master/History.md)
 you should be aware of when migrating from Mongoose 4.x to Mongoose 5.x.
 

docs/migrating_to_6.md

@@ -6,6 +6,9 @@
   }
 </style>
 
+Please note: we plan to discontinue Mongoose 5 support on March 1, 2024.
+Please see our [version support guide](./version-support.html).
+
 There are several [backwards-breaking changes](https://github.com/Automattic/mongoose/blob/master/CHANGELOG.md)
 you should be aware of when migrating from Mongoose 5.x to Mongoose 6.x.
 

docs/source/index.js

@@ -82,6 +82,8 @@ docs['docs/jobs.pug'] = {
 docs['docs/change-streams.md'] = { title: 'MongoDB Change Streams in NodeJS with Mongoose', markdown: true };
 docs['docs/lodash.md'] = { title: 'Using Mongoose with Lodash', markdown: true };
 docs['docs/incompatible_packages.md'] = { title: 'Known Incompatible npm Packages', markdown: true };
+docs['docs/check-version.md'] = { title: 'How to Check Your Mongoose Version', markdown: true };
+docs['docs/version-support.md'] = { title: 'Version Support', markdown: true };
 
 for (const props of Object.values(docs)) {
   props.jobs = jobs;

docs/version-support.md

@@ -0,0 +1,27 @@
+# Version Support
+
+Mongoose 7.x (released February 27, 2023) is the current Mongoose major version.
+We ship all new bug fixes and features to 7.x.
+
+## Mongoose 6
+
+Mongoose 6.x (released August 24, 2021) is currently in legacy support.
+We will continue to ship bug fixes to Mongoose 6 until August 24, 2023.
+After August 24, 2023, we will only ship security fixes, and backport requested fixes to Mongoose 6.
+Please open a [bug report on GitHub](https://github.com/Automattic/mongoose/issues/new?assignees=&labels=&template=bug.yml) to request backporting a fix to Mongoose 6.
+
+We are **not** actively backporting any new features from Mongoose 7 into Mongoose 6.
+Until August 24, 2023, we will backport requested features into Mongoose 6; please open a [feature request on GitHub](https://github.com/Automattic/mongoose/issues/new?assignees=&labels=enhancement%2Cnew+feature&template=feature.yml) to request backporting a feature into Mongoose 6.
+After August 24, 2023, we will not backport any new features into Mongoose 6.
+
+We do not currently have a formal end of life (EOL) date for Mongoose 6.
+However, we will not end support for Mongoose 6 until at least January 1, 2024.
+
+## Mongoose 5
+
+Mongoose 5.x (released January 17, 2018) is currently only receiving security fixes and requested bug fixes.
+Please open a [bug report on GitHub](https://github.com/Automattic/mongoose/issues/new?assignees=&labels=&template=bug.yml) to request backporting a fix to Mongoose 5.
+We will **not** backport any new features from Mongoose 6 or Mongoose 7 into Mongoose 5.
+
+Mongoose 5.x end of life (EOL) is March 1, 2024.
+Mongoose 5.x will no longer receive any updates, security or otherwise, after that date.