diff --git a/docs/version_guarantees.rst b/docs/version_guarantees.rst index 2e216f259..d5747c03c 100644 --- a/docs/version_guarantees.rst +++ b/docs/version_guarantees.rst @@ -20,6 +20,11 @@ which is not private (even if not documented) should not break without notice. Anything in the ``redbot.cogs`` and ``redbot.vendored`` modules or any of their submodules is specifically excluded from being guaranteed. +Method names and names of attributes of classes, functions, extensions, and modules +provided by or provided to the bot should not begin with +``red_`` or be of the form ``__red_*__`` except as documented. +This allows us to add certain optional features non-breakingly without a name conflict. + Any RPC method exposed by Red may break without notice. If you would like something in here to be guaranteed, diff --git a/redbot/core/commands/commands.py b/redbot/core/commands/commands.py index 54283e732..9cf8168ab 100644 --- a/redbot/core/commands/commands.py +++ b/redbot/core/commands/commands.py @@ -261,6 +261,17 @@ class Command(CogCommandMixin, DPYCommand): attributes listed below are simply additions to the ones listed with that class. + .. warning:: + + If you subclass this command, attributes and methods + must remain compatible. + + None of your methods should start with ``red_`` or + be dunder names which start with red (eg. ``__red_test_thing__``) + unless to override behavior in a method designed to be overriden, + as this prefix is reserved for future methods in order to be + able to add features non-breakingly. + Attributes ---------- checks : List[`coroutine function`] @@ -668,7 +679,7 @@ class Command(CogCommandMixin, DPYCommand): See ``format_text_for_context`` for the actual implementation details - Cog creators may override this in their own command classes + Cog creators may override this in their own command and cog classes as long as the method signature stays the same. Parameters @@ -1009,6 +1020,18 @@ class Cog(CogMixin, DPYCog, metaclass=DPYCogMeta): Red's Cog base class This includes a metaclass from discord.py + + .. warning:: + + None of your methods should start with ``red_`` or + be dunder names which start with red (eg. ``__red_test_thing__``) + unless to override behavior in a method designed to be overriden, + as this prefix is reserved for future methods in order to be + able to add features non-breakingly. + + Attributes and methods must remain compatible + with discord.py and with any of red's methods and attributes. + """ __cog_commands__: Tuple[Command]