From b02fa38423293772c6669c1eb9efaf99c75f1740 Mon Sep 17 00:00:00 2001 From: Jakub Kuczys Date: Sun, 10 May 2026 21:51:36 +0200 Subject: [PATCH] Stop referencing V2 everywhere and move migration guide (#6737) --- .github/labeler.yml | 1 - docs/framework_bank.rst | 3 -- docs/framework_config.rst | 43 ------------------- docs/framework_modlog.rst | 2 - docs/framework_rpc.rst | 2 +- docs/guide_cog_creation.rst | 16 +++---- docs/guide_publish_cogs.rst | 4 +- docs/incompatible_changes/index.rst | 1 + .../v2_migration.rst} | 43 +++++++++++++++++++ docs/index.rst | 1 - 10 files changed, 54 insertions(+), 62 deletions(-) rename docs/{guide_migration.rst => incompatible_changes/v2_migration.rst} (52%) diff --git a/.github/labeler.yml b/.github/labeler.yml index 9adf0b94d..e9c3bcc1a 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -266,7 +266,6 @@ - docs/framework_events.rst - docs/guide_cog_creation.rst - docs/guide_cog_creators.rst - - docs/guide_migration.rst - docs/guide_publish_cogs.rst - docs/guide_slash_and_interactions.rst "Category: Docs - Install Guides": diff --git a/docs/framework_bank.rst b/docs/framework_bank.rst index fc1dddb9c..d41d349d0 100644 --- a/docs/framework_bank.rst +++ b/docs/framework_bank.rst @@ -7,9 +7,6 @@ Bank ==== -Bank has now been separated from Economy for V3. New to bank is support for -having a global bank. - *********** Basic Usage *********** diff --git a/docs/framework_config.rst b/docs/framework_config.rst index a8bf4af7d..14dd52679 100644 --- a/docs/framework_config.rst +++ b/docs/framework_config.rst @@ -446,49 +446,6 @@ Of course, if we're less than responsible pet owners, there are consequences:: "how poorly it was taken care of." ) - -************* -V2 Data Usage -************* -There has been much conversation on how to bring V2 data into V3 and, officially, we recommend that cog developers -make use of the public interface in Config (using the categories as described in these docs) rather than simply -copying and pasting your V2 data into V3. Using Config as recommended will result in a much better experience for -you in the long run and will simplify cog creation and maintenance. - -However. - -We realize that many of our cog creators have expressed disinterest in writing converters for V2 to V3 style data. -As a result we have opened up config to take standard V2 data and allow cog developers to manipulate it in V3 in -much the same way they would in V2. The following examples will demonstrate how to accomplish this. - -.. warning:: - - By following this method to use V2 data in V3 you may be at risk of data corruption if your cog is used on a bot - with multiple shards. USE AT YOUR OWN RISK. - -.. code-block:: python - - from redbot.core import Config, commands - - - class ExampleCog(commands.Cog): - def __init__(self): - self.config = Config.get_conf(self, 1234567890) - self.config.init_custom("V2", 1) - self.data = {} - - async def load_data(self): - self.data = await self.config.custom("V2", "V2").all() - - async def save_data(self): - await self.config.custom("V2", "V2").set(self.data) - - - async def setup(bot): - cog = ExampleCog() - await cog.load_data() - await bot.add_cog(cog) - ************************************ Best practices and performance notes ************************************ diff --git a/docs/framework_modlog.rst b/docs/framework_modlog.rst index 4e8d3a84e..2285e410b 100644 --- a/docs/framework_modlog.rst +++ b/docs/framework_modlog.rst @@ -8,8 +8,6 @@ Mod log ======= -Mod log has now been separated from Mod for V3. - *********** Basic Usage *********** diff --git a/docs/framework_rpc.rst b/docs/framework_rpc.rst index 41a821d41..6829a09e0 100644 --- a/docs/framework_rpc.rst +++ b/docs/framework_rpc.rst @@ -9,7 +9,7 @@ RPC 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. +Red 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. Each of those functions must only take JSON serializable parameters and must return JSON serializable objects. diff --git a/docs/guide_cog_creation.rst b/docs/guide_cog_creation.rst index 2f125c17b..96bcca1ea 100644 --- a/docs/guide_cog_creation.rst +++ b/docs/guide_cog_creation.rst @@ -3,11 +3,11 @@ .. role:: python(code) :language: python -======================== -Creating cogs for Red V3 -======================== +===================== +Creating cogs for Red +===================== -This guide serves as a tutorial on creating cogs for Red V3. +This guide serves as a tutorial on creating cogs for Red. It will cover the basics of setting up a package for your cog and the basics of setting up the file structure. We will also point you towards some further resources that may assist @@ -111,8 +111,8 @@ Make sure that both files are saved. Testing your cog ---------------- -To test your cog, you will need a running instance of V3. -Assuming you installed V3 as outlined above, run :code:`redbot-setup` +To test your cog, you will need a running instance of Red. +Assuming you installed Red as outlined above, run :code:`redbot-setup` and provide the requested information. Once that's done, run Red by doing :code:`redbot --dev` to start Red. Complete the initial setup by providing a valid token and setting a @@ -169,6 +169,4 @@ Becoming an Approved Cog Creator Additional resources -------------------- -Be sure to check out the :doc:`/guide_migration` for some resources -on developing cogs for V3. This will also cover differences between V2 and V3 for -those who developed cogs for V2. +If you've developed cogs for V2, you might find `incompatible_changes/v2_migration` document helpful. diff --git a/docs/guide_publish_cogs.rst b/docs/guide_publish_cogs.rst index 5b15fc43e..9ff6f2247 100644 --- a/docs/guide_publish_cogs.rst +++ b/docs/guide_publish_cogs.rst @@ -1,7 +1,7 @@ .. Publishing cogs for V3 -Publishing cogs for Red V3 -========================== +Publishing cogs for Red +======================= Users of Red install 3rd-party cogs using Downloader cog. To make your cog available to install for others, you will have to create a git repository diff --git a/docs/incompatible_changes/index.rst b/docs/incompatible_changes/index.rst index 7a9d88b58..a3dc0cb9f 100644 --- a/docs/incompatible_changes/index.rst +++ b/docs/incompatible_changes/index.rst @@ -10,3 +10,4 @@ Backward incompatible changes future 3.5 + v2_migration diff --git a/docs/guide_migration.rst b/docs/incompatible_changes/v2_migration.rst similarity index 52% rename from docs/guide_migration.rst rename to docs/incompatible_changes/v2_migration.rst index 8e47b0df8..7f0e3ee12 100644 --- a/docs/guide_migration.rst +++ b/docs/incompatible_changes/v2_migration.rst @@ -38,6 +38,49 @@ per-server/member/user/role/channel or global basis. Be sure to check out :doc:`/framework_config` for the API docs for Config as well as a tutorial on using Config. +************* +V2 Data Usage +************* + +There has been much conversation on how to bring V2 data into V3 and, officially, we recommend that cog developers +make use of the public interface in Config (using the categories as described in these docs) rather than simply +copying and pasting your V2 data into V3. Using Config as recommended will result in a much better experience for +you in the long run and will simplify cog creation and maintenance. + +However. + +We realize that many of our cog creators have expressed disinterest in writing converters for V2 to V3 style data. +As a result we have opened up config to take standard V2 data and allow cog developers to manipulate it in V3 in +much the same way they would in V2. The following examples will demonstrate how to accomplish this. + +.. warning:: + + By following this method to use V2 data in V3 you may be at risk of data corruption if your cog is used on a bot + with multiple shards. USE AT YOUR OWN RISK. + +.. code-block:: python + + from redbot.core import Config, commands + + + class ExampleCog(commands.Cog): + def __init__(self): + self.config = Config.get_conf(self, 1234567890) + self.config.init_custom("V2", 1) + self.data = {} + + async def load_data(self): + self.data = await self.config.custom("V2", "V2").all() + + async def save_data(self): + await self.config.custom("V2", "V2").set(self.data) + + + async def setup(bot): + cog = ExampleCog() + await cog.load_data() + await bot.add_cog(cog) + ---- Bank ---- diff --git a/docs/index.rst b/docs/index.rst index 4ee97bbb8..532a405a9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -62,7 +62,6 @@ Welcome to Red - Discord Bot's documentation! :maxdepth: 2 :caption: Red Development Framework Reference: - guide_migration guide_cog_creation guide_slash_and_interactions guide_publish_cogs