Skip to content

Releases: serenity-rs/serenity

v0.12.1

28 Feb 22:35
@arqunis arqunis
v0.12.1
c591d25
Compare
Choose a tag to compare
v0.12.1 Latest
Latest

Thanks to the following for their contributions:

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.
Assets 2

v0.12.0

27 Nov 18:10
@arqunis arqunis
v0.12.0
e3cc527
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.
Compare
Choose a tag to compare
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:

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...
Read more
Assets 2

v0.12.0-rc2

24 Nov 13:05
@arqunis arqunis
v0.12.0-rc2
759c6b4
Compare
Choose a tag to compare
v0.12.0-rc2 Pre-release
Pre-release

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)
Assets 2

v0.12.0-rc

19 Nov 21:14
@arqunis arqunis
v0.12.0-rc
fdf9f37
Compare
Choose a tag to compare
v0.12.0-rc Pre-release
Pre-release

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.

Assets 2

v0.11.7

24 Oct 19:39
@arqunis arqunis
v0.11.7
45e2599
Compare
Choose a tag to compare
v0.11.7

Thanks to the following for their contributions:

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
Assets 2

v0.11.6

30 Jun 16:54
@arqunis arqunis
v0.11.6
ca8f288
Compare
Choose a tag to compare
v0.11.6

Special thanks to @mkrasnitski for writing this changelog ❤️

Thanks to the following for their contributions:

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.

Contributors

mkrasnitski
Assets 2

v0.11.5

29 Jul 15:37
@arqunis arqunis
v0.11.5
4c9a61c
Compare
Choose a tag to compare
v0.11.5

Thanks to the following for their contributions:

Notable changes

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

v0.11.4

19 Jul 21:32
@arqunis arqunis
v0.11.4
5363f2a
Compare
Choose a tag to compare
v0.11.4

Thanks to the following for their contributions:

Notable changes

  • Fix deserialization error of GuildChannel::message_count (@anden3)
Assets 2

v0.11.3

19 Jul 18:37
@arqunis arqunis
v0.11.3
5c9b0af
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.11.3

Thanks to the following for their contributions:

Notable changes

  • Temporarily fix GuildChannel::message_count in a non-breaking way (@GnomedDev)
  • Add support for Auto Moderation feature (@nickelc)
  • Add optional min/max length fields for application command string options (@nickelc)
  • Allow select menu response for modals (@AlexisTM)
  • Add app_permissions field on interactions (@nickelc)
  • Enable Invite::expires_at field (@mkrasnitski)
  • Fix "missing field discriminator" serde error for presence updates (@nickelc)
  • Add webhook example (@NotNorom)
  • Introduce rustversion dependency and backports module (@GnomedDev)
  • Add MessageType::AutoModerationAction enum variant (@nickelc)
  • Attempt to fix lifetime bug around CustomisedHelpData (@mkrasnitski)
  • Auto-impl CacheHttp for Arc<T> if T also implements it (@mkrasnitski)
  • Add audit log action types for scheduled events (@nickelc)
  • Fill gaps in all model::application types (@kangalioo)
  • Add support for slash command localization (@kangalioo)
  • Implement announcement channel following (@GnomedDev)
  • Add event handler methods for scheduled events (@nickelc)
  • Add methods to Webhook to enable direct creation (@mkrasnitski)
  • Consolidate interactions & oauth2 model types into the application module (@nickelc)
  • Fix compile errors in builders when the model feature is disabled (@FallenWarrior2k)
Assets 2

v0.11.2

08 May 15:30
@arqunis arqunis
v0.11.2
502fc8d
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.11.2

Thanks to the following for their contributions:

Added

Changed

Fixed

Removed

Assets 2