From a8091332b82d0da14aa0079ddb2aff78f8f5a2a6 Mon Sep 17 00:00:00 2001 From: Michael H Date: Thu, 18 Jul 2019 21:50:33 -0400 Subject: [PATCH] [Docs] Add version guarantees (#2882) Make some version guarantees. We also need to do a pass over the existing things this would cover and decide if any of them should be made private. --- changelog.d/2882.docs.rst | 1 + docs/guide_cog_creation.rst | 14 ++++++++++++++ docs/index.rst | 1 + docs/version_guarantees.rst | 36 ++++++++++++++++++++++++++++++++++++ 4 files changed, 52 insertions(+) create mode 100644 changelog.d/2882.docs.rst create mode 100644 docs/version_guarantees.rst diff --git a/changelog.d/2882.docs.rst b/changelog.d/2882.docs.rst new file mode 100644 index 000000000..76bdc33a2 --- /dev/null +++ b/changelog.d/2882.docs.rst @@ -0,0 +1 @@ +Create documentation covering what we consider a developer facing breaking change and guarantees regarding them. \ No newline at end of file diff --git a/docs/guide_cog_creation.rst b/docs/guide_cog_creation.rst index 26fb38fc4..116cfb54b 100644 --- a/docs/guide_cog_creation.rst +++ b/docs/guide_cog_creation.rst @@ -35,6 +35,20 @@ a text editor or IDE (examples include `Sublime Text 3 `_, `Atom `_, and `PyCharm `_). +.. attention:: + While you can intentionally override Red's cogs/extensions, this may break things. + We would prefer if people wanted custom behavior + for any core cog/extension, an issue and/or PR is made + Overriding Permissions specifically is dangerous. + + Subclassing to make changes to Red's cogs/extensions + may not be a safe way to stay up to date either, + as changes to cogs and their interactions with red + are not guaranteed to not be breaking. + + Any cogs doing this are doing so at their own risk, + and should also inform users of associated risks. + -------------- Creating a cog -------------- diff --git a/docs/index.rst b/docs/index.rst index 747a2994f..ab262fbd5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,6 +43,7 @@ Welcome to Red - Discord Bot's documentation! framework_modlog framework_rpc framework_utils + version_guarantees .. toctree:: :maxdepth: 2 diff --git a/docs/version_guarantees.rst b/docs/version_guarantees.rst new file mode 100644 index 000000000..247fe6a83 --- /dev/null +++ b/docs/version_guarantees.rst @@ -0,0 +1,36 @@ +.. _version-guarantees: + +========== +Versioning +========== + +Red is versioned as ``major.minor.micro`` + +While this is very similar to SemVer, we have our own set of guarantees. + +Major versions are for project wide rewrites and are not expected in the foreseeable future. + +========== +Guarantees +========== + +Anything in the ``redbot.core`` module or any of its submodules +which is not private (even if not documented) should not break without notice. + +Anything in the ``redbot.cogs`` module or any of it's submodules is specifically +excluded from being guaranteed. + +If you would like something in here to be guaranteed, +open an issue making a case for it to be moved. + +======================= +Breaking Change Notices +======================= + +Breaking changes in Red will be noted in the changelog with a special section. + +Breaking changes may only occur on a minor or major version bump. + +A change not covered by our guarantees may not be considered breaking for these purposes, +while still being documented as a breaking change in internal documentation +for the purposes of other internal APIs.