Fold backwards compatibility policy into changelog

hynek · Nov 25, 2021 · 2c2bcc3 · 2c2bcc3
1 parent e5ad4fb
commit 2c2bcc3
Show file tree

Hide file tree

Showing 4 changed files with 10 additions and 18 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -23,7 +23,7 @@ Please report any harm to [Hynek Schlawack] in any way you find appropriate.
 - Make sure your changes pass our [CI].
   You won't get any feedback until it's green unless you ask for it.
 - Once you've addressed review feedback, make sure to bump the pull request with a short note, so we know you're done.
-- Don’t break [backward compatibility](https://structlog.org/en/latest/backward-compatibility.html).
+- Don’t break backwards compatibility.
 
 
 ## Code

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -3,6 +3,15 @@ Changelog
 
 Versions follow `CalVer <https://calver.org>`_ with a strict backwards compatibility policy.
 
+Put simply, you shouldn't ever be afraid to upgrade ``structlog`` if you're using its public APIs.
+Whenever there is a need to break compatibility, it is announced here in the changelog, and raises a ``DeprecationWarning`` for a year (if possible) before it's finally really broken.
+
+.. warning::
+
+   You cannot rely on the default settings and the `structlog.dev` module.
+   They may be adjusted in the future to provide a better experience when starting to use ``structlog``.
+   So please make sure to **always** properly configure your applications.
+
 
 21.4.0 (UNRELEASED)
 -------------------

diff --git a/docs/backward-compatibility.rst b/docs/backward-compatibility.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -78,7 +78,6 @@ API Reference
 .. toctree::
    :maxdepth: 1
 
-   backward-compatibility
    license
    changelog