Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add explicit mention of word 'provisional' for version guarantee excl…
Browse files Browse the repository at this point in the history
…usions (Cog-Creators#6311)
Jackenmen authored and Dav-Git committed Sep 8, 2024
1 parent 9d64002 commit 6f18f68
Showing 9 changed files with 29 additions and 19 deletions.
10 changes: 5 additions & 5 deletions CHANGES.rst
Original file line number Diff line number Diff line change
@@ -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`)
- **Core - Commands Package** - `commands.NoParseOptional <NoParseOptional>` is no longer provisional and is now fully supported part of API (:issue:`4142`)
- |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 <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`)

2 changes: 1 addition & 1 deletion docs/framework_commands.rst
Original file line number Diff line number Diff line change
@@ -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>`_

3 changes: 2 additions & 1 deletion docs/framework_rpc.rst
Original file line number Diff line number Diff line change
@@ -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.
12 changes: 9 additions & 3 deletions docs/version_guarantees.rst
Original file line number Diff line number Diff line change
@@ -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:

=======================
6 changes: 4 additions & 2 deletions redbot/core/_rpc.py
Original file line number Diff line number Diff line change
@@ -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 <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 @@ 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 <developer-guarantees-exclusions>` basis.
Backwards incompatible changes (up to and including removal of the RPC) may occur if deemed necessary.
Parameters
----------
4 changes: 2 additions & 2 deletions redbot/core/bot.py
Original file line number Diff line number Diff line change
@@ -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 <developer-guarantees-exclusions>`.
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 <developer-guarantees-exclusions>`.
This exists for use in ``cog_unload`` for cogs which replace the formatter
2 changes: 1 addition & 1 deletion redbot/core/commands/commands.py
Original file line number Diff line number Diff line change
@@ -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 <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
5 changes: 3 additions & 2 deletions redbot/core/commands/converter.py
Original file line number Diff line number Diff line change
@@ -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 <developer-guarantees-exclusions>`
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 <developer-guarantees-exclusions>`.
UserInputOptional = Optional

if TYPE_CHECKING:
4 changes: 2 additions & 2 deletions redbot/core/commands/help.py
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit 6f18f68

Please sign in to comment.