Add notes about releases and deprecations

docs/contents.rst.inc

@@ -8,7 +8,7 @@ User Documentation
    cli
    plugins/index
    faq
-   deprecations
+   releases
 
 
 Developer Documentation

docs/deprecations.rst

@@ -1,46 +0,0 @@
-.. _deprecations:
-
-Deprecation Policy
-==================
-
-A release of FlaskBB may deprecate existing features and begin emitting
-:class:`~flaskbb.deprecation.FlaskBBDeprecation` warnings.
-
-These warnings are on by default and will announce for the first time each
-deprecated usage is detected. If you want to ignore these warnings, this
-behavior can be modified by setting ``DEPRECATION_LEVEL`` in your configuration
-file or setting ``FLASKBB_DEPRECATION_LEVEL`` in your environment to a level
-from the builtin warnings module.
-
-For more details on interacting with warnings see
-`the official documentation on warnings <https://docs.python.org/3/library/warnings.html>`_.
-
-
-.. note::
-
-    If you are developing on FlaskBB the level for FlaskBBDeprecation warnings
-    is always set to ``error`` when running tests to ensure that deprecated
-    behavior isn't being relied upon. If you absolutely need to downgrade to a
-    non-exception level, use pytest's recwarn fixture and set the level with
-    warnings.simplefilter
-
-
--- Insert Details of deprecation timeline --
-
-I suggest following something like Django's policy of at least 2 feature
-versions. But semvar suggests that backwards incompatible changes are a major
-version bump. :shrug:
-
-
-Deprecation Helpers
-~~~~~~~~~~~~~~~~~~~
-
-FlaskBB also publicly provides tools for handling deprecations as well and are
-open to use by plugins or other extensions to FlaskBB.
-
-.. module:: flaskbb.deprecation
-
-.. autoclass:: FlaskBBWarning
-.. autoclass:: FlaskBBDeprecation
-.. autoclass:: RemovedInFlaskBB3
-.. autofunction:: deprecated

docs/development/api/deprecations.rst

@@ -0,0 +1,29 @@
+.. _deprecations:
+
+Deprecation Helpers
+===================
+
+FlaskBB publicly provides tools for handling deprecations and are open to use
+by plugins or other extensions to FlaskBB. For example if a plugin wants to
+deprecate a particular function it could do::
+
+    from flaskbb.deprecation import FlaskBBDeprecation, deprecated
+
+    class RemovedInPluginV2(FlaskBBDeprecation):
+        version = (2, 0, 0)
+
+
+    @deprecated
+    def thing_removed_in_plugin_v2():
+        ...
+
+
+Now the plugin will issue deprecation warnings in the same fashion as the rest
+of FlaskBB.
+
+.. module:: flaskbb.deprecation
+
+.. autoclass:: FlaskBBWarning
+.. autoclass:: FlaskBBDeprecation
+.. autoclass:: RemovedInFlaskBB3
+.. autofunction:: deprecated

docs/development/api/index.rst

@@ -15,3 +15,4 @@ and provided implementations where appropriate.
    authentication
    accountmanagement
    tokens
+   deprecations

docs/releases.rst

@@ -0,0 +1,51 @@
+.. _releasing:
+
+Releases
+========
+
+Releases for FlaskBB can be found on `pypi <https://pypi.org/project/FlaskBB>`_
+as well as on `github <https://github.com/flaskbb/flaskbb>`_. Each release of
+FlaskBB will have a git tag such as ``v2.0.0`` as well as a branch such as
+``2.0.0``. The ``master`` branch is always the latest version of FlaskBB and
+versions are cut from this branch.
+
+FlaskBB loosely follows semantic versions (semver) where all releases in each
+major version strive to be backwards compatibility, though sometimes this will
+be broken in order to apply a bugfix or security patch. When this occurs the
+release notes will contain information about this.
+
+Releases follow no particular cadence.
+
+
+Deprecation Policy
+~~~~~~~~~~~~~~~~~~
+
+A release of FlaskBB may deprecate existing features and begin emitting
+:class:`~flaskbb.deprecation.FlaskBBDeprecation` warnings.
+
+
+These warnings are on by default and will announce for the first time each
+deprecated usage is detected. If you want to ignore these warnings, this
+behavior can be modified by setting ``DEPRECATION_LEVEL`` in your configuration
+file or setting ``FLASKBB_DEPRECATION_LEVEL`` in your environment to a level
+from the builtin warnings module.
+
+For more details on interacting with warnings see
+`the official documentation on warnings <https://docs.python.org/3/library/warnings.html>`_.
+
+
+In general, a feature deprecated in a release will not be fully removed until
+the next major version. For example, a feature deprecated in 2.1.0 would not
+be removed until 3.0.0. There may be exceptions to this, such as if a deprecated
+feature is found to be a security risk.
+
+.. note::
+
+    If you are developing on FlaskBB the level for FlaskBBDeprecation warnings
+    is always set to ``error`` when running tests to ensure that deprecated
+    behavior isn't being relied upon. If you absolutely need to downgrade to a
+    non-exception level, use pytest's recwarn fixture and set the level with
+    warnings.simplefilter
+
+
+For more details on using deprecations in plugins or extensions, see :ref:`deprecations`.