Document Backwards Compatibility, SemVer and Breaking Changes (jupyte…

…rlab#14355)

* Added backwards compatibility and semver notes to the docs

* Update backwards compatibility/semver notes.

docs/source/developer/contributing.rst

@@ -56,10 +56,33 @@ Documentation <https://jupyter.readthedocs.io/en/latest/contributing/content-con
 and `Code of
 Conduct <https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md>`__.
 
+.. _versioning_notes:
+
+Backwards Compatibility, Versions and Breaking Changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+New versions of JupyterLab may break backwards compatibility with extensions and other Jupyter
+customizations. Breaking changes are kept to a minimum where possible. JupyterLab development
+and release cycles follow `semantic versioning <https://semver.org/>`__, so when breaking
+changes are necessary, they are communicated via the version numbering scheme. In short, this
+means that, for a JupyterLab version X.Y.Z:
+
+- Major version (X) number changes indicate breaking changes (NOT backwards compatible)
+- Minor Version (Y) number changes indicate a backwards compatible addition of new features
+- Patch version (Z) number changes indicate backwards compatible bug fixes
+
+Contributions to JupyterLab extensions and other customizations should plan for possible
+breaking changes. Consider documenting your maintenance plans to users in these projects.
+You may also wish to consider pinning the major version of JupyterLab when developing
+extensions (in your package metadata).
+
 We maintain the **two most recently released major versions of JupyterLab**,
 JupyterLab v2 and JupyterLab v3. After JupyterLab v4 is released, we will no
-longer maintain v2.
-All JupyterLab v2 users are strongly advised to upgrade as soon as possible.
+longer maintain v2. All JupyterLab v2 users are strongly advised to upgrade
+as soon as possible.
+
+Languages, Tools and Processes
+------------------------------
 
 All source code is written in
 `TypeScript <https://www.typescriptlang.org/Handbook>`__. See the `Style

docs/source/extension/extension_dev.rst

@@ -12,6 +12,14 @@ A JupyterLab extension is a package that contains a number of JupyterLab plugins
 
 See the sections below for more detailed information, or browse the rest of this page for an overview.
 
+.. warning::
+    Your extensions may break with new releases of JupyterLab. As noted in :ref:`versioning_notes`,
+    JupyterLab development and release cycles follow semantic versioning, so we recommend planning
+    your development process to account for possible future breaking changes that may disrupt users
+    of your extensions. Consider documenting your maintenance plans to users in your project, or
+    setting an upper bound on the version of JupyterLab your extension is compatible with in your
+    project's package metadata.
+
 .. toctree::
    :maxdepth: 1
 

docs/source/getting_started/installation.rst

@@ -8,6 +8,13 @@ Installation
 
 JupyterLab can be installed using ``conda``, ``mamba``, ``pip``, ``pipenv`` or ``docker``.
 
+.. warning::
+    New versions of JupyterLab may break backwards compatibility with extensions and other
+    Jupyter customizations. As noted in :ref:`versioning_notes`, JupyterLab development and
+    release cycles follow semantic versioning, so we recommend planning your installation and
+    upgrade procedures to account for possible breaking changes that may disrupt your usage
+    of JupyterLab and any related tools that are critical to your workflows.
+
 conda
 -----