v0.12.4

This is a hotfix release to fix broken behaviour of Message::author_permissions before it is relied on.

Thanks to the following for their contributions:

• @GnomedDev
• @jamesbt365

Deprecations

• #3037 Permission methods which do not respect channel permission overrides are now deprecated, use the _in variants.

Additions

• #3008 From<&User> has been added to CreateEmbedAuthor, to avoid consuming the user.

Fixes

• #3037 Message::author_permissions now respects permission overrides, as it is documented to.
• #3039 Message::author_permissions now respects SEND_MESSAGES_IN_THREADS when used in threads.

Documentation improvements

• #3038 Documentation for Guild::threads has been expanded.

v0.12.3

Thanks to the following for their contributions:

• @FabseGP
• @GnomedDev
• @HiccupEnthusiast
• @MarkusTheOrt
• @NiiightmareXD
• @ValgulNecron
• @gBasil
• @ivinjabraham
• @jamesbt365
• @limonfort
• @m1sk9
• @mkrasnitski
• @onzecki
• @rhgndf
• @stormofice
• @thmasq
• @thou-vow

Deprecations

• #2894 Message(Id)::link_ensured can be replaced by Message(Id)::link if recieved via event, or MessageId::link if the message was recieved via a HTTP request.
• #2905 CreateInteractionResponse::PremiumRequired has been deprecated and replaced with Premium Buttons.
• #3030 GuildChannel::permissions_for_user has been deprecated, use the new Message::author_permissions helper or Guild::user_permissions_in.

Additions

• #2891 Guild Incident message types have been added to MessageType.
• #2913 CreateButton now implements From<Button>.
• #2914 User::display_name has been added, as users may have two different names now.
• #2920 Support for Application Emojis has been added, getting rid of those "emoji servers" many bots required.
• #2905 Support for Premium Buttons has been added, which link to the store page of a chosen SKU.
• #2926 A method to get the role icon URL has been added.
• #2939 Some missing fields have been added to to CurrentApplicationInfo.
• #2946 Support for the Get Guild Role endpoint has been added.
• #2960 Support for the Get Sticker Pack by Id endpoint has been added.
• #2962 Some missing entries in GuildMemberFlags have been added.
• #2950 The missing USE_EXTERNAL_APPS permission has been added.
• #2987 A builder for the Get Entitlements endpoint has been added.
• #2996 MessageReferenceKind has been added to start supporting forwarding.
• #3001 {PartialGuild, Guild}::partial_member_permissions has been added for more efficent permissions checking
• #3013 Interaction responses can now send polls.
• #3018 User App support has been stablised, usable without unstable_discord_api.
• #3021 Support for Entry Point Commands has been added.
• #3030 A Message::author_permissions helper has been added, alongside Permissions::dm_permissions.

Deserialisation Fixes

• #2887, #2893
  Messages with reactions no longer fail to deserialize due to super reaction changes.
• #2917 Application no longer fails to deserialize with unstable_discord_api
• #3032 Guilds with an @everyone role at position -1 no longer fail to deserialise.

General fixes

• #2886 A typo has been fixed in GuildId::members_iter documentation.
• #2906 CreateAttachment documentation has been updated to be more consistent with other builders.
• #2911 CreateEmbedAuthor documentation can now spell embed correctly.
• Pushed to Current AuthorizingIntegrationOwners is now usable, as the field was previously private.
• #2945 (Partial)Guild::member_permissions is now usable without cache.
• #2973 ChannelId::delete_messages documentation has been expanded to document the single item case.
• #2959 The rules for attachment names for local attachments in embeds have now been documented.
• #3005 The fields of BulkBanResponse have been made public.
• #3006 The bulk_ban endpoint is now usable, previously unusable due to Send issues.

v0.12.2

Thanks to the following for their contributions:

• @bend-n
• @GnomedDev
• @jamesbt365
• @MidSpike
• @mkrasnitski
• @RegenJacob

Deprecations

Continuing with the deprecations started in 0.12.1, many more methods and fields have been deprecated in order to make an easier upgrade path to 0.13.

These deprecation messages include a migration path, it is recommended to go one by one using cargo check and migrate each warning to reduce the burden migrating to 0.13. Following is a list of the deprecation PRs and the justification for these changes.

• (#2791) The Channel::is_nsfw method was wrong, useless, and served better by GuildChannel::nsfw
• (#2794) These cache methods needed arcane borrow checker dances internally, and obscure the simplicity of the cache.
• (#2816) Member::highest_role_info is now strictly less powerful than the new Guild::member_highest_role and can avoid a cache lookup if used correctly.
• (#2825)
• • Guild::is_large is less accurate than Guild::large
• • Message::is_own is super simple to implement yourself
• • Message::is_private simply checks if Message::guild_id is none.
• (#2838) Event::PresencesReplace does not exist, and is a relic from when serenity supported user accounts.
• (#2861) TeamMember::permissions is always ["*"], so is useless.

Other notable changes

• (#2790) Added CreateMessage::enforce_nonce, to prevent sending duplicate messages.
• (#2801) Added EditProfile::banner, allowing banners to be set for bots.
• (#2810) Added ChannelId::get_thread_member.
• (#2812) Added Guild::partial_member_permissions_in, which can be used to avoid fetching a Member in message events just to check permissions.
• (#2819) Added From<User> for CreateEmbedAuthor, setting the author name and icon to the User's info.
• (#2813) Added UserId::direct_message, so you don't need a full User to direct message.
• (#2834) Added Http::default_allowed_mentions to set the AllowedMentions to be used with every request.
• (#2830) Added Guild(Id)::bulk_ban, allowing bulk banning without hitting rate limits.
• (#2836) Added support for Message Polls, including reading and sending them.
• (#2807) Added support for User Apps, alllowing user-installable application commands.
• (#2882) Added support for super reactions.
• Many documentation fixes and other optimisations to improve memory and CPU usage.

v0.12.1

Thanks to the following for their contributions:

• @arqunis
• @GnomedDev
• @jamesbt365
• @kangalio
• @logand22
• @mkrasnitski
• @SenseiHiraku
• @vaporoxx
• @vidhanio
• @Xaeroxe
• @yanorei32

Notable changes

In this release, the standard framework has been deprecated (#2733).

As Discord continues to endorse and evolve application commands (/... commands, user commands, message commands, etc.), the standard framework becomes increasingly outdated. Bots are also steadily losing (and already have lost) access to contents of messages, making it difficult to build a prefix-only bot. Unless you plan on restricting your bot to only accept commands in DMs, allowing its presence in only fewer than 100 guilds, or presenting a reasonable justification to Discord for permission to continue using message contents, you should migrate to application commands. We recommend poise, which supports writing both prefix and application commands with a #[command] macro like the standard framework.

Why not just update the framework?

Poise already exists and is better than the standard framework. Efforts should be directed at improving poise instead. To support application commands would require an overhaul of the standard framework, as they are special (for instance, Discord parses arguments on behalf of the bot and passes them as structured data, whereas for prefix commands, the bot must parse by itself).

Smaller, but still notable changes

• (#2621) Add a temporary cache for messages.
• (#2649) Deprecate RoleId::to_role_cached - Use Guild::roles instead.
• (#2726) Pack bitflags - Reduces alignments of bitflags! types, resulting in a smaller memory footprint.
• (#2696) Support attachments in forum posts.
• (#2560) Add support for monetization apis.
• (#2648) Deprecate inefficient emoji helpers - use the emoji methods on guildid/guild instead.

v0.12.0

This release turned out to be one of serenity's largest ever, with well over 300 PRs in total! It contains quite a few major breaking changes to the API. Therefore, the changelog for this release also serves as a migration guide for users upgrading from the 0.11 series.

Thanks to the following for their contributions:

• [@arqunis]
• [@alakhpc]
• [@AngelOnFira]
• [@Bloectasy]
• [@campbellcole]
• [@cheesycod]
• [@crivasr]
• [@darkyeg]
• [@fenhl]
• [@GnomedDev]
• [@jamesbt365]
• [@Joshument]
• [@kangalio]
• [@Kneemund]
• [@LaytonGB]
• [@marcantoinem]
• [@Miezhiko]
• [@Milo123459]
• [@mkrasnitski]
• [@nickelc]
• [@oSumAtrIX]
• [@Ruthenic]
• [@Sergiovan]
• [@skreborn]
• [@StckOverflw]
• [@tatsuya6502]
• [@tazz4843]
• [@vaporoxx]
• [@Xaeroxe]

Builders

The closure-based API for constructing requests using the builder pattern has been ripped out and replaced. In place of closures, users must now pass in builder types directly. For example, in serenity 0.11, code like the following was very common:

let channel = guild
    .create_channel(&http, |c| c.name("my-test-channel").kind(ChannelType::Text))
    .await?;

Now, users instead write the following code:

let builder = CreateChannel::new("my-test-channel").kind(ChannelType::Text);
let channel = guild.create_channel(&http, builder).await?;

Or, inline like so:

let channel = guild
    .create_channel(&http, CreateChannel::new("my-test-channel").kind(ChannelType::Text))
    .await?;

Note that in this particular example, the channel name is now a mandatory field that must be passed in when constructing the builder. Mutating the builder with subsequent calls to CreateChannel::name will change the underlying value. Additionally, all methods on builders now take mut self and return Self, instead of taking and returning &mut self/&mut Self. This allows for explicit construction as in the second example above. Also, builders no longer wrap a pub HashMap<&'static str, T>; the hashmap has been flattened into concrete private fields.

Some benefits to this new approach to builders are:

1. Because every closure has a type unique to it, each call to a method taking a closure would be monomorphized separately, resulting in binary bloat. This is no longer the case.
2. Builders can be constructed once and then cloned and re-used multiple times.
3. Enforcement of field requirements (as dictated by the Discord API docs) provides compile-time request validation.

Attachments

• The AttachmentType enum has been replaced with a CreateAttachment builder struct. This struct has the file, path, and url constructors that eagerly evaluate the data passed to them - CreateAttachment simply stores the resulting raw data. This is in contrast to AttachmentType which lazily carried filepaths/urls with it, and had data and filename methods for resolving them. Additionally, the CreateAttachment::to_base64 method can be used to manually encode an attachment if needed.
• A new EditAttachments builder struct has been added for use with the attachments method on the EditMessage, EditWebhookMessage, and EditInteractionResponse builders. This new builder provides finer control when editing a message's existing attachments or uploading additional ones. Also, the following methods have been renamed to more accurately reflect their behavior:

serenity v0.11	serenity v0.12
EditMessage::attachment	EditMessage::new_attachment
EditMessage::add_existing_attachment	EditMessage::keep_existing_attachment
EditWebhookMessage::clear_existing_attachments	EditWebhookMessage::clear_attachments
EditInteractionResponse::clear_existing_attachments	EditInteractionResponse::clear_attachments

Collectors

Collectors have been redesigned and simplified at no cost to expressibility. There is now a generic collector::collect function which takes a closure as argument, letting you filter events as they stream in.

• The specific collectors (ComponentInteractionCollector, ModalInteractionCollector, MessageCollector, and ReactionCollector) are simply convenience structs that wrap this underlying function.
• EventCollector is now deprecated, as its use usually involved anti-patterns around fallibility. However, its functionality can still be replicated using collector::collect. See example 10 for more details.
• The RelatedId and RelatedIdsForEventType types have been removed as they were only used by EventCollector. Methods for retrieving them from events have also been removed; if users wish to extract "related" ids from an event, they should do so directly from the event's fields. The removed methods are the following:
  • Event::user_id
  • Event::guild_id
  • Event::channel_id
  • Event::message_id
  • EventType::related_ids

Commands

In an effort to shorten long names and make import paths less unwieldy, Serenity now uses command instead of application_command in all places, except for the Permissions::USE_APPLICATION_COMMANDS constant. This includes methods on the Http, GuildId, Guild, PartialGuild, and Command types, as well as a few other miscellaneous places:

serenity v0.11	serenity v0.12
Http::*_{global,guild}_application_command*	Http::*_{global,guild}_command*
{GuildId,Guild,PartialGuild}::*_application_command*	{GuildId,Guild,PartialGuild}::*_command*
Command::*_global_application_command*	Command::*_global_command*
Interaction::application_command	Interaction::command
EventHandler::application_command_permissions_update	EventHandler::command_permissions_update
Route::ApplicationCommand*	Route::Command*
Permissions::use_application_commands	Permissions::use_commands

Additionally, the following command types have been renamed:

serenity v0.11	serenity v0.12
CreateApplicationCommand	CreateCommand
CreateApplicationCommandOption	CreateCommandOption
CreateApplicationCommandPermissionData	CreateCommandPermission
CreateApplicationCommandPermissionsData	EditCommandPermissions
CommandPermission	CommandPermissions
CommandPermissionData	CommandPermission

Furthermore, the methods on CreateCommandPermission, such as new, kind, etc. have been replaced with constructors for each type of permission, e.g. role, user, channel, etc., to avoid a possible mismatch between kind and the id that gets passed in.

Finally, the {GuildId,Guild,PartialGuild}::create_command_permission method has been renamed to edit_command_permission to more accurately reflect its behavior.

Cache

• Cache methods now return a CacheRef type that wraps a reference into the cache. Other methods that returned a map, now return a wrapper type around a reference to the map, with a limited API to prevent accidental deadlocks. This all helps reduce the number of clones when querying the cache. Those wishing to replicate the old behavior can simply call .clone() on the return type to obtain the wrapped data.
• CacheSettings has new fields time_to_live, cache_guilds, cache_channels, and cache_users, allowing cache configuration on systems with memory requirements; whereas previously, memory-constrained systems were forced to disable caching altogether.
• Caching for PrivateChannels (aka DM channels) has been removed, as they are never sent across the gateway by Discord. Therefore, the Cache::{private_channel, private_channels} methods have been removed, and Cache::guild_channel has been renamed to just Cache::channel. Additionally, some uses of the Channel enum in return types have been replaced with either GuildChannel or PrivateChannel as seen fit.

IDs

All *Id types have had their internal representations made private. Therefore, the API has changed as follows:

serenity v0.11	serenity v0.12
ExampleId(12345)	ExampleId::new(12345)
example_id.as_u64()	example_id.get()

Note that all *Id types now implement Into<u64> and Into<i64>. Additionally, attempting to instantiate an id with a value of 0 will panic.

Also, the implementations of FromStr for the UserId, RoleId, and ChannelId types now expect an integer rather than a mention string. The following table shows the new expected input strings:

	serenity v0.11	serenity v0.12
ChannelId	<#81384788765712384>	81384788765712384
RoleId	<@&136107769680887808>	136107769680887808
UserId	<@114941315417899012> or <@!114941315417899012>	114941315417899012

Users wishing to parse mentions should either parse into a Mention object, or use the utils::{parse_user_mention, parse_role_mention, parse_channel_mention} methods.

Interactions

The various interaction types have been renamed as follows:

serenity v0.11	serenity v0.12
ApplicationCommandInteraction	CommandInteraction
MessageComponentInteraction	ComponentInteraction
ModalSubmitInteraction	ModalInteraction

Method names on interaction types have been shortened in the following way:

serenity v0.11	serenity v0.12
create_interaction_response	create_response
create_followup_message	create_followup
delete_original_interaction_response	delete_response
delete_followup_message	delete_followup
edit_original_interaction_response	edit_response
edit_followup_message	edit_followup
`get_interaction_respon...

v0.12.0-rc2

This is the second iteration of 0.12's Release Candidate. Notable inclusions since the prior iteration are:

• (#2612) Make Event::Unknown wrap UnknownEvent again
• (#2592) Add experimental typesize support
• (#2615) Rework framework builders to not use closures (this just makes the standard framework's builders consistent with the rest of the release)

v0.12.0-rc

This is the Release Candidate for v0.12.0. For the list of changes made (which there are a ton), see the CHANGELOG file at the root of the repository.

v0.11.7

Thanks to the following for their contributions:

• @arqunis
• @B-2U
• @Collin-Swish
• @caoculus
• @Dean-Coakley
• @HexPandaa
• @mattfbacon
• @mkrasnitski
• @OnlyCS

Notable changes

• (#2493) Add MessageComponentInteraction::edit_original_message() for editing the original message of the message component.
• (#2504) Implement std::str::FromStr for the ID types to allow converting from a string. This does not affect the pre-existing implementation on ChannelId, RoleId, and UserId.
• (#2506) Add missing set_components() methods on EditInteractionResponse and EditWebhookMessage
• (#2533) Add additional delete_reaction and delete_reactions methods for deleting reactions to ChannelId, GuildChannel, and Message.
• (#2562) Bump base64 dependency to 0.21

v0.11.6

Special thanks to @mkrasnitski for writing this changelog ❤️

Thanks to the following for their contributions:

• @acdenisSK
• @Chronophylos
• @cyril-marpaud
• @dclamage
• @dpytaylo
• @float3
• @ghost
• @GnomedDev
• @ivancernja
• @jontze
• @kangalio
• @MarkusTheOrt
• @mkrasnitski
• @NinekoTheCat
• @Polyhistorian
• @rand0m-cloud
• @sandlotie
• @ShashankKumarSaxena
• @squili
• @Web-44
• @zackradisic
• @zzzzDev4

Notable changes

• (#2076) Make Timestamp usable regardless of the chrono or time features.
• (#2077) Deprecate modifying command application permissions in bulk. The corresponding endpoint is already deprecated by Discord.
• (#2130) Standard Framework: Implicitly set BucketBuilder::await_ratelimits to 1 upon BucketBuilder::delay_action being set.
• (#2133) Add Voice channels to the list of text-based channel types.
• (#2136) Add an event for HTTP ratelimits, and a corresponding EventHandler::ratelimit method.
• (#2154) Add the following fields to MessageUpdateEvent:
  • mention_channels
  • reactions
  • components
  • sticker_items
• (#2155) Expose Shard::handle_event publicly.
• (#2214) Add User::member, as well as Message:{thread, application_id} fields.
• (#2223, #2290) Add a defer_ephemeral helper method to many interaction types.
• (#2265) Add as_* and into_* helper methods to the Interaction type for converting to each of its respective variants.
• (#2281) Add the UserPublicFlags::ACTIVE_DEVELOPER flag.
• (#2298) Add the following fields to guild channel, relevant for forums:
  • flags
  • total_messages_sent
  • available_tags
  • applied_tags
  • default_reaction_emoji
  • default_thread_rate_limit_per_user
  • default_sort_order
• (#2330) Add support for owner_id in thread and forum channels.
• (#2346) Add the SUPPRESS_NOTIFICATIONS message flag.
• (#2431) Add support for getting application commands with localizations via the following methods:
  • Http::get_{guild,global}_application_commands_with_localizations
  • Command::get_global_application_commands_with_localizations
  • {GuildId,Guild,PartialGuild}::get_application_commands_with_localizations
• (#2444) Add a remove_all_attachments method to EditMessage.

v0.11.5

Thanks to the following for their contributions:

• @bumblepie

Notable changes

• Make select menu values optional to fix deserialization of message component interactions (@bumblepie)