From d8b1472b54627affab9ebff613c978ca7a439c1a Mon Sep 17 00:00:00 2001 From: ItsDrike Date: Thu, 16 Feb 2023 19:01:59 +0100 Subject: [PATCH] Add versions guarantees page --- LICENSE-THIRD-PARTY.txt | 3 +++ changes/34.docs.md | 1 + docs/index.rst | 1 + docs/pages/changelog.rst | 3 +++ docs/pages/version_guarantees.rst | 35 +++++++++++++++++++++++++++++++ 5 files changed, 43 insertions(+) create mode 100644 changes/34.docs.md create mode 100644 docs/pages/version_guarantees.rst diff --git a/LICENSE-THIRD-PARTY.txt b/LICENSE-THIRD-PARTY.txt index e5b05189..2081fb52 100644 --- 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 new file mode 100644 index 00000000..cd2b991b --- /dev/null +++ b/changes/34.docs.md @@ -0,0 +1 @@ +Add version guarantees page diff --git a/docs/index.rst b/docs/index.rst index 3c54d29b..9f299be1 100644 --- 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 index 2ef12e61..68f630ee 100644 --- 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 new file mode 100644 index 00000000..0f99688f --- /dev/null +++ b/docs/pages/version_guarantees.rst @@ -0,0 +1,35 @@ +Version Guarantees +================== + +This library follows `semantic versioning model `_, 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.