docs: 2.x migration docs

docs/src/Guides/98 2.x Migration.md

@@ -0,0 +1,110 @@
+# 1.x -> 2.x Migration Guide
+2.x Was a rewrite of various parts of Naff, and as such, there are a few breaking changes. This guide will help you migrate your code from 1.x to 2.x.
+
+Please note; there are other additions to 2.x, but they are not breaking changes, and as such, are not covered in this guide.
+
+## Misc.
+- All `edit` methods are now keyword arguments only.
+  - The exception is `content` on message edits, which is positional.
+- `context.interaciton_id` is now an `int` instead of a `str`.
+
+## Selects
+To simplify SelectMenus, NAFF made some changes to how SelectMenus are used.
+- Options can now be and *reasonable* type, be it `SelectOption`, `dict`, `iterable` or `str`
+- All parameters are now keyword only, excpet for `options` which remains positional or keyword
+- `Select` was renamed to `StringSelectMenu`
+- New select menus were implemented to support API changes
+  - https://discord.com/developers/docs/interactions/message-components#select-menus
+  - `UserSelectMenu`
+  - `RoleSelectMenu`
+  - `MentionableSelectMenu`
+  - `ChannelSelectMenu`
+  - `ChannelSelectMenu`
+
+### Before
+```python
+from naff import Select, SelectOption
+await channel.send(
+        "Old SelectUX",
+        components=Select(
+            options=[
+                SelectOption("test1", "test1"),
+                SelectOption("test2", "test2"),
+                SelectOption("test3", "test3"),
+            ],
+            placeholder="test",
+        ),
+    )
+```
+
+### After
+```python
+from naff import StringSelectMenu
+
+await channel.send(
+        "New SelectMenu Menu UX test", components=StringSelectMenu(["test1", "test2", "test3"], placeholder="test")
+    )
+```
+
+## Listeners
+Listeners have received a series of ease-of-use updates for both extension and bot developers alike.
+
+- All internal listeners now have a `is_default_listener` attribute to make it easier to differentiate between the library's listeners and user defined listeners.
+- `override_default_listeners` allows you to completely override the library's listeners with your own.
+  - Note it might be worth looking into processors if you're doing this; as they allow acting on the raw-payloads before they're processed by the library.
+- All event objects now have a shortcut to listen to them via `BaseEvent.listen(coro, Client)`
+- Listeners can now be delayed until the client is ready with a `delay_until_ready` argument.
+
+## Events
+- All event objects now have a shortcut to listen to them via `BaseEvent.listen(coro, Client)`
+- New Events!
+  - `ComponentCompletion` - Dispatched after the library ran any component callback.
+  - `AutocompleteCompletion` - Dispatched after the library ran any autocomplete callback.
+  - `ModalCompletion` - Dispatched after the library ran any modal callback.
+  - `Error` - Dispatched whenever the libray encounters an unhandled exception.
+    - Previously this was done by overriding the `on_error` method on the client, or in extensions
+  - `CommandError` - Dispatched whenever a command encounters an unhandled exception.
+  - `ComponentError` - Dispatched whenever a component encounters an unhandled exception.
+  - `AutocompleteError` - Dispatched whenever an autocomplete encounters an unhandled exception.
+  - `ModalError` - Dispatched whenever a modal encounters an unhandled exception.
+  - `NewThreadCreate` - Dispatched whenever a thread is newly created
+  - `GuildAvailable` - Dispatched whenever a guild becomes available
+    - note this requires the guild cache to be enabled
+  - `ApplicationCommandPermissionsUpdate` - Dispatched whenever a guild's application command permissions are updated
+  - `VoiceUserDeafen` - Dispatched whenever a user's deafen status changes
+  - `VoiceUserJoin` - Dispatched whenever a user joins a voice channel
+  - `VoiceUserLeave` - Dispatched whenever a user leaves a voice channel
+  - `VoiceUserMove` - Dispatched whenever a user moves to a different voice channel
+  - `VoiceUserMute` - Dispatched whenever a user's mute status changes
+- Event Renamed
+  - `Button` has been renamed to `ButtonPressed` to avoid naming conflicts
+- All events with a `context` attribute have had it renamed to `ctx` for consistency
+
+## Client Changes
+- dm commands can now be disabled completely via the `disable_dm_commands` kwarg
+- `Client.interaction_tree` offers a command tree of all application commands registered to the client
+- The `Client` now sanity checks the cache configuration
+- The `Client` will no longer warn you if a cache timeout occurs during startup
+  - These are caused by T&S shadow-deleting guilds, and are not a concern
+- `async_startup_tasks` are now performed as soon as the client successfully connects to the REST API
+  - Note this is before the gateway connection is established, use a `on_ready` listener if you need to wait for the gateway connection
+- Application Command syncing is now more error tolerant
+
+## Extensions
+- Extensions no longer require a `setup` entrypoint function.
+  - For complex setups, I would still advise using an entrypoint function
+
+## Caching
+- A `NullCache` object is now used to represent a disabled cache, to use it use `create_cache(0, 0, 0)` in a client kwarg as before
+  - This is a very niche-use-case and most people won't need to use it
+- The `Client` will log a warning if `NullCache` is used for sanity checking
+- The serializer now respects `no_export` metadata when using `as_dict`
+
+## Forums
+- Forums now utilise the new API spec instead of the private-beta API
+- A new `NewThreadCreate` event is now dispatched for brand new threads
+- Add various helper methods to `Forum` objects
+- `create_post` now handles `str`, `int` `Tag` objects for available tags
+
+## Emoji
+- `PartialEmoji.from_str` can now return None if no emoji is found

docs/src/Guides/index.md

@@ -106,5 +106,11 @@ These guides are meant to help you get started with the library and offer a poin
 
     Whats different between NAFF and discord.py?
 
+-   [__:material-package-up: Migration from discord.py__](98 2.x Migration.md)
+
+    ---
+
+    How do I migrate from 1.x to 2.x?
+
 
 </div>