From 6f18f680c9e8ec764974b7ea086b81f349310313 Mon Sep 17 00:00:00 2001 From: Jakub Kuczys Date: Mon, 18 Mar 2024 01:15:17 +0100 Subject: [PATCH] Add explicit mention of word 'provisional' for version guarantee exclusions (#6311) --- CHANGES.rst | 10 +++++----- docs/framework_commands.rst | 2 +- docs/framework_rpc.rst | 3 ++- docs/version_guarantees.rst | 12 +++++++++--- redbot/core/_rpc.py | 6 ++++-- redbot/core/bot.py | 4 ++-- redbot/core/commands/commands.py | 2 +- redbot/core/commands/converter.py | 5 +++-- redbot/core/commands/help.py | 4 ++-- 9 files changed, 29 insertions(+), 19 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 16bfcbb0a05..6b39d423d80 100644 --- a/CHANGES.rst +++ b/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 ` ``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 `), `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 ` for more information - **Core - Bot Class** - Added `bot.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 ` for more details (:issue:`4011`) -- **Core - Commands Package** - `commands.NoParseOptional ` is no longer provisional and is now fully supported part of API (:issue:`4142`) +- |cool| **Core - Commands Package** - Added a `provisional API ` for replacing the help formatter. See `documentation ` for more details (:issue:`4011`) +- **Core - Commands Package** - `commands.NoParseOptional ` is no longer `provisional ` 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 ` status of RPC (:issue:`3862`) - Revised install instructions (:issue:`3847`) - Improved navigation in `document about updating Red ` (:issue:`3856`, :issue:`3849`) diff --git a/docs/framework_commands.rst b/docs/framework_commands.rst index 38a57470706..59da090600e 100644 --- a/docs/framework_commands.rst +++ b/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 ` and may change without prior notice or warning. Updates to this will be communicated on `this issue `_ diff --git a/docs/framework_rpc.rst b/docs/framework_rpc.rst index 45757b128d6..41a821d4152 100644 --- a/docs/framework_rpc.rst +++ b/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 ` 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. diff --git a/docs/version_guarantees.rst b/docs/version_guarantees.rst index 4cc444ef6c9..c5978094a45 100644 --- a/docs/version_guarantees.rst +++ b/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: ======================= diff --git a/redbot/core/_rpc.py b/redbot/core/_rpc.py index 5cd2e1660e8..28515687a1d 100644 --- a/redbot/core/_rpc.py +++ b/redbot/core/_rpc.py @@ -156,7 +156,8 @@ def register_rpc_handler(self, method): 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 ` basis. + Backwards incompatible changes (up to and including removal of the RPC) may occur if deemed necessary. Parameters ---------- @@ -180,7 +181,8 @@ def unregister_rpc_handler(self, method): 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 ` basis. + Backwards incompatible changes (up to and including removal of the RPC) may occur if deemed necessary. Parameters ---------- diff --git a/redbot/core/bot.py b/redbot/core/bot.py index bb77723b3c7..f3a9135d6e5 100644 --- a/redbot/core/bot.py +++ b/redbot/core/bot.py @@ -255,7 +255,7 @@ def set_help_formatter(self, formatter: commands.help.HelpFormatterABC): Set's Red's help formatter. .. warning:: - This method is provisional. + This method is `provisional `. The formatter must implement all methods in @@ -296,7 +296,7 @@ def reset_help_formatter(self): Resets Red's help formatter. .. warning:: - This method is provisional. + This method is `provisional `. This exists for use in ``cog_unload`` for cogs which replace the formatter diff --git a/redbot/core/commands/commands.py b/redbot/core/commands/commands.py index 85ff1dc0a58..22ffc34ccdf 100644 --- a/redbot/core/commands/commands.py +++ b/redbot/core/commands/commands.py @@ -840,7 +840,7 @@ async def red_get_data_for_user(self, *, user_id: int) -> MutableMapping[str, io .. note:: - This method is documented provisionally + This method is documented `provisionally ` 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 diff --git a/redbot/core/commands/converter.py b/redbot/core/commands/converter.py index 8af18dcaea0..9ef82cdffad 100644 --- a/redbot/core/commands/converter.py +++ b/redbot/core/commands/converter.py @@ -3,7 +3,8 @@ ================== 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 ` +and are marked as such. """ import functools import math @@ -492,7 +493,7 @@ def __class_getitem__(cls, key): #: 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 `. UserInputOptional = Optional if TYPE_CHECKING: diff --git a/redbot/core/commands/help.py b/redbot/core/commands/help.py index 66920780d59..111d6d302dc 100644 --- a/redbot/core/commands/help.py +++ b/redbot/core/commands/help.py @@ -82,7 +82,7 @@ class HelpSettings: .. warning:: - This class is provisional. + This class is `provisional `. """ @@ -190,7 +190,7 @@ class HelpFormatterABC(abc.ABC): .. warning:: - This class is documented but provisional with expected changes. + This class is documented but `provisional ` with expected changes. In the future, this class will receive changes to support invoking the help command without context.