Merge pull request #142 from kennethdyer/DOCSP-25995-version

DOCSP-25995 version reference guidelines

Author: Chris Cho

source/style-guide/style/index.txt

@@ -37,6 +37,7 @@ instructions for applying style conventions.
    /style-guide/style/plurals
    /style-guide/style/prepositions
    /style-guide/style/product-names-version-numbers
+   /style-guide/style/version
    /style-guide/style/punctuation
    /style-guide/style/symbols
    /style-guide/style/tables

source/style-guide/style/product-names-version-numbers.txt

@@ -1,8 +1,8 @@
 .. _product-names-version-numbers:
 
-=================================
-Product Names and Version Numbers
-=================================
+=============
+Product Names 
+=============
 
 .. default-domain:: mongodb
 

source/style-guide/style/version.txt

@@ -0,0 +1,117 @@
+.. _version-numbers:
+
+===============
+Version Numbers
+===============
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. |add| replace:: `versionadded <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded>`__
+.. |change| replace:: `versionchanged <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionchanged>`__
+.. |deprecated| replace:: `deprecated <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated>`__
+
+Versions are unique names assigned to product releases that are packaged 
+with a set of features at a specific point in time. 
+MongoDB products follow `semantic versioning 
+<https://en.wikipedia.org/w/index.php?title=Software_versioning&oldid=1147438049>`__ 
+Use version numbers or names to refer to a particular release of a product, 
+such as identifying when a new feature was introduced or removed.
+
+General Guidelines
+------------------
+
+With the exception of release notes and changelogs, which serve as historical
+documents, avoid referencing product release versions that we no longer support.
+For example, when a release of MongoDB Server reaches End of Life (EOL), 
+remove references to that release.
+
+You can omit the following release-specific references:
+
+* Features introduced in an EOL release are outdated.
+
+* Features removed in an EOL release are unavailable in all supported releases.
+
+* Features changed in an EOL release represent preexisting behavior in all 
+  supported releases.
+
+
+Use the following guidelines to reference product versions so that
+you can more easily find these references when the release reaches EOL:
+
+* Use version directives whenever possible.  The version directives make it
+  easier to locate on the page and in the {+rst+}:
+
+  .. code-block:: rst
+
+     .. versionadded:: 6.0
+
+  If a version reference needs more explanation, add the content 
+  to the directive block:
+
+  .. code-block:: rst
+
+     .. versionchanged:: 4.4
+
+        This command returns the following output:
+
+  If you need to call out multiple versions, set the most recent version
+  first, then reference the others in a phrase afterwards.
+
+  .. code-block:: rst
+
+     .. versionadded:: 6.0 *(Also available in MongoDB 5.0.)*
+
+  The italics marker matches the directive output.
+
+  Snooty supports the following version directives: 
+
+  .. hlist::
+     :columns: 3
+
+     * |add|
+     * |change|
+     * |deprecated|
+
+* To refer to a version inline, include the product
+  name before the version number, (for example, ``MongoDB 5.0``).  This ensures 
+  that a search for version numbers correctly matches product and release.
+
+* Do **not** reference versions freeform or with the phrase ``version X.X``.
+  These references are much harder to identify programmatically as references 
+  to a specific product version.
+
+Identify EOL Releases
+---------------------
+
+You can find references to EOL releases of MonogDB using grep:
+
+.. code-block:: shell
+
+   $ grep -nRI \
+         -e ".. versionadded:: [0-9]" \
+         -e ".. versionchanged:: [0-9]" \
+         -e ".. deprecated:: [0-9]" \
+         -e "MongoDB [0-9]" \
+         source | \
+         grep -v "6\.2" | \
+         grep -v "6\.1" | \
+         grep -v "6\.0" | \
+         grep -v "5\.3" | \
+         grep -v "5\.1" | \
+         grep -v "5\.0" | \
+         grep -v "4\.4" | \
+         grep -v "4\.2" | \
+         grep -v "source/release-notes"
+   source/sharding.txt:128:- In MongoDB 4.0 and earlier, a document's shard key field value is
+   source/sharding.txt:351:   Starting in MongoDB 4.0.3, setting up zones and zone ranges *before*
+   source/sharding.txt:379:Starting in MongoDB 3.6, :doc:`change streams </changeStreams>` are
+   ...
+
+Whenever a release goes EOL, remove the relevant ``grep -v`` line to ensure that
+its version references begin to appear in the results.