From 1243298b34ba68e5f7b5a2ccb1c0520a360f1f9b Mon Sep 17 00:00:00 2001 From: Rapptz Date: Mon, 8 Apr 2019 01:10:14 -0400 Subject: [PATCH] Add some version guarantees to the documentation. --- docs/api.rst | 11 +++++------ docs/index.rst | 1 + docs/version_guarantees.rst | 30 ++++++++++++++++++++++++++++++ docs/whats_new.rst | 9 +++++++++ 4 files changed, 45 insertions(+), 6 deletions(-) create mode 100644 docs/version_guarantees.rst diff --git a/docs/api.rst b/docs/api.rst index 9208dafdc..7371537da 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -16,20 +16,19 @@ The following section outlines the API of discord.py. Version Related Info --------------------- -There are two main ways to query version information about the library. +There are two main ways to query version information about the library. For guarantees, check :ref:`version_guarantees`. .. data:: version_info - A named tuple that is similar to `sys.version_info`_. + A named tuple that is similar to :obj:`py:sys.version_info`. - Just like `sys.version_info`_ the valid values for ``releaselevel`` are + Just like :obj:`py:sys.version_info`_ the valid values for ``releaselevel`` are 'alpha', 'beta', 'candidate' and 'final'. - .. _sys.version_info: https://docs.python.org/3.5/library/sys.html#sys.version_info - .. data:: __version__ - A string representation of the version. e.g. ``'0.10.0-alpha0'``. + A string representation of the version. e.g. ``'1.0.0rc1'``. This is based + off of `PEP-440 `_. Client ------- diff --git a/docs/index.rst b/docs/index.rst index ba8c22164..4cb193640 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -50,6 +50,7 @@ Additional Information discord faq whats_new + version_guarantees If you still can't find what you're looking for, try in one of the following pages: diff --git a/docs/version_guarantees.rst b/docs/version_guarantees.rst new file mode 100644 index 000000000..7909bd6b5 --- /dev/null +++ b/docs/version_guarantees.rst @@ -0,0 +1,30 @@ +.. _version_guarantees: + +Version Guarantees +===================== + +The library follows a `semantic versioning principle `_ which means that the major version is updated every time there is an incompatible API change. However due to the lack of guarantees on the Discord side when it comes to breaking changes along with the fairly dynamic nature of Python it can be hard to discern what can be considered a breaking change and what isn't. + +The 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 then it is not part of the public API and is thus bound to change. This includes attributes that start with an underscore or functions without an underscore that are not documented. + +.. note:: + + The examples below are non-exhaustive. + +Examples of Breaking Changes +------------------------------ + +- Changing the default parameter value to something else. +- Renaming a function without an alias to an old function. +- Adding or removing parameters to an event. + +Examples of Non-Breaking Changes +---------------------------------- + +- Adding or removing private underscored attributes. +- Adding an element into the ``__slots__`` of a data class. +- Changing the behaviour of a function to fix a bug. +- Changes in the documentation. +- Modifying the internal HTTP handling. +- Upgrading the dependencies to a new version, major or otherwise. + diff --git a/docs/whats_new.rst b/docs/whats_new.rst index 069138ae4..7130841f6 100644 --- a/docs/whats_new.rst +++ b/docs/whats_new.rst @@ -8,6 +8,15 @@ Changelog This page keeps a detailed human friendly rendering of what's new and changed in specific versions. +.. _vp1p0p0: + +v1.0.0 +-------- + +The changeset for this version are too big to be listed here, for more information please +see :ref:`the migrating page `. + + .. _vp0p16p6: v0.16.6