Add versions guarantees page

py-mine · Feb 16, 2023 · d8b1472 · d8b1472
1 parent b14178b
commit d8b1472
Show file tree

Hide file tree

Showing 5 changed files with 43 additions and 0 deletions.
diff --git a/LICENSE-THIRD-PARTY.txt b/LICENSE-THIRD-PARTY.txt
@@ -16,6 +16,9 @@ Applies to:
         - .github/workflows/prepare-release.yml: Workflow heavily inspired by original
         - .github/scripts/normalize_coverage.py: Entire file
         - docs/_static/extra.css: Entire file
+    - Copyright (c) 2015-present Rapptz
+      All rights reserved.
+        - docs/pages/version_guarantees.rst: Entire file
 ---------------------------------------------------------------------------------------------------
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/changes/34.docs.md b/changes/34.docs.md
@@ -0,0 +1 @@
+Add version guarantees page
diff --git a/docs/index.rst b/docs/index.rst
@@ -11,6 +11,7 @@ Content
     examples/index.rst
     pages/faq.rst
     pages/changelog.rst
+    pages/version_guarantees.rst
     pages/contributing.rst
     pages/code-of-conduct.rst
 

diff --git a/docs/pages/changelog.rst b/docs/pages/changelog.rst
@@ -1,6 +1,9 @@
 Changelog
 =========
 
+.. seealso::
+   Check out what can and can't change between the library versions. :doc:`version_guarantees`
+
 .. attention::
     Major and minor releases also include the changes specified in prior development releases.
 

diff --git a/docs/pages/version_guarantees.rst b/docs/pages/version_guarantees.rst
@@ -0,0 +1,35 @@
+Version Guarantees
+==================
+
+This library follows `semantic versioning model <https:semver.org>`_, which means the major version
+is updated every time there is an incompatible (breaking) change made to the public API. However
+due to the fairly dynamic nature of Python, it can be hard to discern what can be considered a
+breaking change, and what isn't.
+
+First thing to keep in mind is that breaking changes only apply to **publicly documented
+functions and classes**. If it's not listed in the documentation here, it's an internal feature,
+that's it's not considered a part of the public API, and thus is bound to change. This includes
+documented attributes that start with an underscore.
+
+.. note::
+   The examples below are non-exhaustive.
+
+Examples of Breaking Changes
+----------------------------
+
+* Changing the default parameter value of a function to something else.
+* Renaming (or removing) a function without an alias to the old function.
+* Adding or removing parameters of a function.
+* Removing deprecated alias to a renamed function
+
+Examples of Non-Breaking Changes
+--------------------------------
+
+* Changing function's name, while providing a deprecated alias.
+* Renaming (or removing) private underscored attributes.
+* Adding an element into `__slots__` of a data class.
+* Changing the behavior of a function to fix a bug.
+* Changes in the typing behavior of the library.
+* Changes in the documentation.
+* Modifying the internal protocol connection handling.
+* Updating the dependencies to a newer version, major or otherwise.