doc: Have a versioning policy (getsentry#424)

untitaker · web-flow · commit 2e50fff13671 · 2019-07-11T15:06:02.000+02:00
Not a lot of Python projects seem to have this because everybody just
assumes semver until stuff starts breaking.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,3 +1,30 @@
+# Changelog and versioning
+
+## Versioning Policy
+
+This project follows [semver](https://semver.org/), with three additions:
+
+* Semver says that major version `0` can include breaking changes at any time.
+  Still, it is common practice to assume that only `0.x` releases (minor
+  versions) can contain breaking changes while `0.x.y` releases (patch
+  versions) are used for backwards-compatible changes (bugfixes and features).
+  This project also follows that practice.
+
+* All undocumented APIs are considered internal. They are not part of this
+  contract.
+
+* Certain features (e.g. integrations) may be explicitly called out as
+  "experimental" or "unstable" in the documentation. They come with their own
+  versioning policy described in the documentation.
+
+We recommend to pin your version requirements against `0.x.*` or `0.x.y`.
+Either one of the following is fine:
+
+```
+sentry-sdk>=0.10.0,<0.11.0
+sentry-sdk==0.10.1
+```
+
 ## 0.10.1
 
 * Fix bug where the SDK would yield a deprecation warning about
@@ -22,6 +49,7 @@
 
 * Revert a change in 0.9.3 that prevented passing a ``unicode``
   string as DSN to ``init()``.
+
 ## 0.9.3
 
 * Add type hints for ``init()``.
@@ -49,7 +77,6 @@
 * Fix distribution information for mypy support (add `py.typed` file). Thanks
   Ran Benita!
 
-
 ## 0.9.0
 
 * The SDK now captures `SystemExit` and other `BaseException`s when coming from
