Add explicit mention of word 'provisional' for version guarantee exclusions (#6311)

CHANGES.rst

@@ -443,7 +443,7 @@ Changes
 - **Core - Bot Class** - The ``channel`` parameter of `Red.embed_requested()` now accepts any messageable guild channel (:issue:`5576`)
 - **Core - Bot Class** - The bot's color is now set earlier in the launch process (:issue:`5627`)
 - **Core - Bot Class** - `Red.remove_cog()` returns a `commands.Cog` instance now (:issue:`5600`)
-- **Core - Commands Package** - The provisional ``Literal`` converter has been replaced with discord.py's own `typing.Literal` implementation (:issue:`5600`)
+- **Core - Commands Package** - The `provisional <developer-guarantees-exclusions>` ``Literal`` converter has been replaced with discord.py's own `typing.Literal` implementation (:issue:`5600`)
 - **Core - Commands Package** - Added a ``join_character`` parameter to `Red.send_interactive()` and `Context.send_interactive()` to allow choosing the character messages are joined with (:issue:`5901`, :issue:`5902`)
 - **Core - Modlog** - `modlog.set_modlog_channel()` can now accept `discord.VoiceChannel` and `discord.StageChannel` (:issue:`5709`)
 - **Core - Utils Package** - `menu()` now defaults to `DEFAULT_CONTROLS` if the ``controls`` argument is not passed (:issue:`5678`)
@@ -2077,13 +2077,13 @@ Additions
     - Cog disabling is automatically applied for commands and only needs to be done manually for things like event listeners; see `recommendations-for-cog-creators` for more information
 - |cool| **Core** - Added data request API (:issue:`4045`,  :issue:`4169`)
 
-    - New special methods added to `redbot.core.commands.Cog`: `red_get_data_for_user()` (documented provisionally), `red_delete_data_for_user()`
+    - New special methods added to `redbot.core.commands.Cog`: `red_get_data_for_user()` (documented `provisionally <developer-guarantees-exclusions>`), `red_delete_data_for_user()`
     - New special module level variable added: ``__red_end_user_data_statement__``
     - These methods and variables should be added by all cogs according to their documentation; see `recommendations-for-cog-creators` for more information
     - New ``info.json`` key added: ``end_user_data_statement``; see `Info.json format documentation <info-json-format>` for more information
 - **Core - Bot Class** - Added `bot.message_eligible_as_command() <Red.message_eligible_as_command()>` utility method which can be used to determine if a message may be responded to as a command (:issue:`4077`)
-- |cool| **Core - Commands Package** - Added a provisional API for replacing the help formatter. See `documentation <framework-commands-help>` for more details (:issue:`4011`)
+- |cool| **Core - Commands Package** - Added a `provisional API <developer-guarantees-exclusions>` for replacing the help formatter. See `documentation <framework-commands-help>` for more details (:issue:`4011`)
-- **Core - Commands Package** - `commands.NoParseOptional <NoParseOptional>` is no longer provisional and is now fully supported part of API (:issue:`4142`)
+- **Core - Commands Package** - `commands.NoParseOptional <NoParseOptional>` is no longer `provisional <developer-guarantees-exclusions>` and is now fully supported part of API (:issue:`4142`)
 
 Changes
 *******
@@ -2435,7 +2435,7 @@ Documentation changes
 Changes
 *******
 
-- Added information about provisional status of RPC (:issue:`3862`)
+- Added information about `provisional <developer-guarantees-exclusions>` status of RPC (:issue:`3862`)
 - Revised install instructions (:issue:`3847`)
 - Improved navigation in `document about updating Red <update_red>` (:issue:`3856`, :issue:`3849`)
 

docs/framework_commands.rst

@@ -66,7 +66,7 @@ Help Functionality
 
 .. warning::
 
-    The content in this section is provisional and may change
+    The content in this section is `provisional <developer-guarantees-exclusions>` and may change
     without prior notice or warning. Updates to this will be communicated
     on `this issue <https://github.com/Cog-Creators/Red-DiscordBot/issues/4084>`_
 

docs/framework_rpc.rst

@@ -6,7 +6,8 @@ RPC
 
 .. important::
 
-  RPC support is included in Red on a provisional basis. Backwards incompatible changes (up to and including removal of the RPC) may occur if deemed necessary.
+  RPC support is included in Red on a `provisional <developer-guarantees-exclusions>` basis.
+  Backwards incompatible changes (up to and including removal of the RPC) may occur if deemed necessary.
 
 V3 comes default with an internal RPC server that may be used to remotely control the bot in various ways.
 Cogs must register functions to be exposed to RPC clients.

docs/version_guarantees.rst

@@ -112,12 +112,18 @@ This allows us to add certain optional features non-breakingly without a name co
 
 Any RPC method exposed by Red may break without notice.
 
-Any exclusion from these guarantees should be noted in the documentation of
-the affected attribute, function, class, or method.
-
 If you would like something in here to be guaranteed,
 open an issue making a case for it to be moved.
 
+.. _developer-guarantees-exclusions:
+
+Exclusions
+----------
+
+Any exclusion from these guarantees should be noted in the documentation of
+the affected attribute, function, class, or method. The term "provisional"
+may be used in documentation to note such exclusions.
+
 .. _breaking-change-notices:
 
 =======================

redbot/core/_rpc.py

@@ -156,7 +156,8 @@ class RPCMixin:
             The return value of handler methods must also be JSON serializable.
 
         .. important::
-            RPC support is included in Red on a provisional basis. Backwards incompatible changes (up to and including removal of the RPC) may occur if deemed necessary.
+            RPC support is included in Red on a `provisional <developer-guarantees-exclusions>` basis.
+            Backwards incompatible changes (up to and including removal of the RPC) may occur if deemed necessary.
 
         Parameters
         ----------
@@ -180,7 +181,8 @@ class RPCMixin:
         method is not previously registered.
 
         .. important::
-            RPC support is included in Red on a provisional basis. Backwards incompatible changes (up to and including removal of the RPC) may occur if deemed necessary.
+            RPC support is included in Red on a `provisional <developer-guarantees-exclusions>` basis.
+            Backwards incompatible changes (up to and including removal of the RPC) may occur if deemed necessary.
 
         Parameters
         ----------

redbot/core/bot.py

@@ -255,7 +255,7 @@ class Red(
         Set's Red's help formatter.
 
         .. warning::
-            This method is provisional.
+            This method is `provisional <developer-guarantees-exclusions>`.
 
 
         The formatter must implement all methods in
@@ -296,7 +296,7 @@ class Red(
         Resets Red's help formatter.
 
         .. warning::
-            This method is provisional.
+            This method is `provisional <developer-guarantees-exclusions>`.
 
 
         This exists for use in ``cog_unload`` for cogs which replace the formatter

redbot/core/commands/commands.py

@@ -840,7 +840,7 @@ class CogMixin(CogGroupMixin, CogCommandMixin):
 
         .. note::
 
-            This method is documented provisionally
+            This method is documented `provisionally <developer-guarantees-exclusions>`
             and may have minor changes made to it.
             It is not expected to undergo major changes,
             but nothing utilizes this method yet and the inclusion of this method

redbot/core/commands/converter.py

@@ -3,7 +3,8 @@ commands.converter
 ==================
 This module contains useful functions and classes for command argument conversion.
 
-Some of the converters within are included provisionally and are marked as such.
+Some of the converters within are included `provisionally <developer-guarantees-exclusions>`
+and are marked as such.
 """
 import functools
 import math
@@ -492,7 +493,7 @@ if not TYPE_CHECKING:
     #: multiple types, but such usage is not supported and will fail at runtime
     #:
     #: .. warning::
-    #:    This converter class is still provisional.
+    #:    This converter class is still `provisional <developer-guarantees-exclusions>`.
     UserInputOptional = Optional
 
 if TYPE_CHECKING:

redbot/core/commands/help.py

@@ -82,7 +82,7 @@ class HelpSettings:
 
     .. warning::
 
-        This class is provisional.
+        This class is `provisional <developer-guarantees-exclusions>`.
 
     """
 
@@ -190,7 +190,7 @@ class HelpFormatterABC(abc.ABC):
 
     .. warning::
 
-        This class is documented but provisional with expected changes.
+        This class is documented but `provisional <developer-guarantees-exclusions>` with expected changes.
 
         In the future, this class will receive changes to support
         invoking the help command without context.