Compatibility Policy
====================

Semantic Versioning
-------------------

PyMongo's version numbers follow `semantic versioning`_: each version number
is structured "major.minor.patch". Patch releases fix bugs, minor releases
add features (and may fix bugs), and major releases include API changes that
break backwards compatibility (and may add features and fix bugs).

Deprecation
-----------

Before we remove a feature in a major release, PyMongo's maintainers make an
effort to release at least one minor version that *deprecates* it. We add
"**DEPRECATED**" to the feature's documentation, and update the code to raise a
`DeprecationWarning`_. You can ensure your code is future-proof by running
your code with the latest PyMongo release and looking for DeprecationWarnings.

The interpreter silences DeprecationWarnings by default. For example, the
following code uses the deprecated ``insert`` method but does not raise any
warning:

.. code-block:: python

    # "insert.py" (with PyMongo 3.X)
    from pymongo import MongoClient

    client = MongoClient()
    client.test.test.insert({})

To print deprecation warnings to stderr, run python with "-Wd"::

  $ python3 -Wd insert.py
  insert.py:4: DeprecationWarning: insert is deprecated. Use insert_one or insert_many instead.
    client.test.test.insert({})

You can turn warnings into exceptions with "python -We"::

  $ python3 -We insert.py
  Traceback (most recent call last):
    File "insert.py", line 4, in <module>
      client.test.test.insert({})
    File "/home/durin/work/mongo-python-driver/pymongo/collection.py", line 2906, in insert
      "instead.", DeprecationWarning, stacklevel=2)
  DeprecationWarning: insert is deprecated. Use insert_one or insert_many instead.

If your own code's test suite passes with "python -We" then it uses no
deprecated PyMongo features.

.. seealso:: The Python documentation on `the warnings module`_,
   and `the -W command line option`_.

.. _semantic versioning: https://semver.org/

.. _DeprecationWarning:
  https://docs.python.org/3/library/exceptions.html#DeprecationWarning

.. _the warnings module: https://docs.python.org/3/library/warnings.html

.. _the -W command line option: https://docs.python.org/3/using/cmdline.html#cmdoption-W
