From bd6e8f50078eba95812246c4a43e853b42d21b57 Mon Sep 17 00:00:00 2001 From: Michael H Date: Sat, 18 Jul 2020 16:41:49 -0400 Subject: [PATCH 1/6] Document prefix preservation --- redbot/core/commands/commands.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/redbot/core/commands/commands.py b/redbot/core/commands/commands.py index e2215958f87..5db706c8b05 100644 --- a/redbot/core/commands/commands.py +++ b/redbot/core/commands/commands.py @@ -864,6 +864,14 @@ 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_`` 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. + """ __cog_commands__: Tuple[Command] From 3e90ce7f88feb87e142e14b2b0da788ee85dd8d2 Mon Sep 17 00:00:00 2001 From: Michael H Date: Sat, 18 Jul 2020 17:55:07 -0400 Subject: [PATCH 2/6] more docs --- redbot/core/commands/commands.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/redbot/core/commands/commands.py b/redbot/core/commands/commands.py index 5db706c8b05..7490a0b3ecd 100644 --- a/redbot/core/commands/commands.py +++ b/redbot/core/commands/commands.py @@ -250,6 +250,12 @@ 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. + Additionally, the prefix `red_` for names is reserved for future use. + Attributes ---------- checks : List[`coroutine function`] @@ -657,7 +663,7 @@ def format_shortdoc_for_context(self, ctx: "Context") -> str: 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 @@ -872,6 +878,9 @@ class Cog(CogMixin, DPYCog, metaclass=DPYCogMeta): 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] From 778b9e26798aa1c6cd01564226ce68476eceb59d Mon Sep 17 00:00:00 2001 From: Michael H Date: Sat, 18 Jul 2020 17:59:52 -0400 Subject: [PATCH 3/6] ref fix --- redbot/core/commands/commands.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/redbot/core/commands/commands.py b/redbot/core/commands/commands.py index 7490a0b3ecd..5f5939309c3 100644 --- a/redbot/core/commands/commands.py +++ b/redbot/core/commands/commands.py @@ -254,7 +254,7 @@ class Command(CogCommandMixin, DPYCommand): If you subclass this command, attributes and methods must remain compatible. - Additionally, the prefix `red_` for names is reserved for future use. + Additionally, the prefix ``red_`` for names is reserved for future use. Attributes ---------- From d586e69952982b67169e448dc2462b3311fccea0 Mon Sep 17 00:00:00 2001 From: Michael H Date: Mon, 20 Jul 2020 18:42:16 -0400 Subject: [PATCH 4/6] update reservations to include dunders --- redbot/core/commands/commands.py | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/redbot/core/commands/commands.py b/redbot/core/commands/commands.py index 5f5939309c3..a0eada967e6 100644 --- a/redbot/core/commands/commands.py +++ b/redbot/core/commands/commands.py @@ -254,7 +254,12 @@ class Command(CogCommandMixin, DPYCommand): If you subclass this command, attributes and methods must remain compatible. - Additionally, the prefix ``red_`` for names is reserved for future use. + + None of your methods should start with ``red_`` or + be dunder methods 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 ---------- @@ -873,8 +878,9 @@ class Cog(CogMixin, DPYCog, metaclass=DPYCogMeta): .. warning:: - None of your methods should start with ``red_`` unless - to override behavior in a method designed to be overriden, + None of your methods should start with ``red_`` or + be dunder methods 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. From bd4298d053bffc5a332f095163384b44e766c29b Mon Sep 17 00:00:00 2001 From: Michael H Date: Mon, 20 Jul 2020 18:46:52 -0400 Subject: [PATCH 5/6] meh --- redbot/core/commands/commands.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/redbot/core/commands/commands.py b/redbot/core/commands/commands.py index a0eada967e6..17d2dec5494 100644 --- a/redbot/core/commands/commands.py +++ b/redbot/core/commands/commands.py @@ -255,8 +255,8 @@ class Command(CogCommandMixin, DPYCommand): If you subclass this command, attributes and methods must remain compatible. - None of your methods should start with ``red_`` or - be dunder methods which start with red (eg. ``__red_test_thing__``) + 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. @@ -879,7 +879,7 @@ class Cog(CogMixin, DPYCog, metaclass=DPYCogMeta): .. warning:: None of your methods should start with ``red_`` or - be dunder methods which start with red (eg. ``__red_test_thing__``) + 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. From d8ad0bd77245684e1e857a67994a0fed488e761a Mon Sep 17 00:00:00 2001 From: Michael H Date: Tue, 21 Jul 2020 17:16:29 -0400 Subject: [PATCH 6/6] Add a broad exclusion in the guarantees section --- docs/version_guarantees.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/version_guarantees.rst b/docs/version_guarantees.rst index 2e216f259f4..d5747c03c37 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,