Skip to content

Latest commit

 

History

History
3091 lines (2601 loc) · 154 KB

CHANGELOG.md

File metadata and controls

3091 lines (2601 loc) · 154 KB
Raw

Change Log

All notable changes to this project will be documented in this file. This project mostly adheres to Semantic Versioning.

0.5.8 - 2018-08-12

This is a hotfix release for incorrect routing and to fix a large number of broken documentation links.

Thanks to the following for their contributions:

Upgrade Path

Per c:71edc3a, methods on ID structs like ChannelId::find have been deprecated and replace with UserId::to_channel_cached. Similarly, methods like GuildId::get have been replaced with GuildId::to_partial_guild. While the original methods have not been removed, they have been deprecated.

Added

Fixed

Changed

  • [model] Add to_*, as_* methods on Id types, deprecate get and find methods (@Lakelezz) c:71edc3a

Misc.

0.5.7 - 2018-08-09

This is a hotfix release for an incorrect warning about cache deadlocking during event dispatches in the client and fixing some routing method typos due to the HTTP rewrite.

Thanks to the following for their contributions:

Fixed

Misc.

0.5.6 - 2018-08-07

This is a bugfix release that fixes a long-standing bug causing shards to randomly die under certain rare conditions when dispatching the Ready event, and compilation of the cache and client features without the framework feature. This also contains an internal rewrite of the HTTP module.

The minimum required rustc version is now pinned at 1.25.0.

Thanks to the following for their contributions:

Upgrade Path

Per c:01e3c33, Context::edit_profile has been deprecated. Call serenity::http::edit_profile instead.

Added

Fixed

Changed

Misc.

0.5.5 - 2018-07-25

This release is mostly a bugfix release. Thanks to the following for their contributions:

Added

Fixed

Changed

  • [model] Make Invite::guild and RichInvite::guild optional (@zeyla) c:3a647e3

Misc.

0.5.4 - 2018-06-07

Thanks to the following for their contributions:

Added

Fixed

Misc.

0.5.3 - 2018-05-01

Thanks to the following for their contributions:

Added

Fixed

Misc.

0.5.2 - 2018-04-14

This release contains the usual bugfixes and helper methods.

Thanks to the following for their contributions:

Added

Fixed

Misc.

0.5.1 - 2018-01-31

This release contains a number of fixes, a few more model helper methods, and additional framework features.

Thanks to the following for their contributions:

Added

Fixed

Changed

Misc.

0.5.0 - 2018-01-20

This release is a rewrite of the client and gateway internals with a minimal amount of breaking changes for userland code. These changes are mainly to prepare for Tokio and to reduce the number of atomic operations per received event, reducing the number of atomic operations by roughly 85%. The framework has also seen a rewrite, and is now centered around a trait-based design.

Thanks to the following for their contributions:

Upgrade Path

Per c:91c8ec4, the Guild::default_channel and Guild::default_channel_guarenteed methods now return Option<Arc<Mutex<GuildChannel>>> instead of Option<GuildChannel>. This avoids a clone. To access the channel, you just have to retrieve a read or write lock by doing guild.default_channel()?.read() or guild.default_channel()?.write().

Per c:14b9222, there is a new Member::default_channel() function that returns the default channel for the user. This no longer returns the channel with the same ID as the guild itself, as this behaviour was changed by Discord. A member's "default channel" is now the top-most channel that it has permission to view. Accordingly, Guild::default_channel matches this behaviour.

Per c:93e0a42, the library now uses the parking_lot crate's Mutex and RwLock implementations over the stdlib's. parking_lots implementations are more efficient, do not poison due to lock drops on unwinding, and implement eventual fairness.

To account for this, change all Mutex lock retrievals and RwLock read and write lock retrievals to not unwrap. parking_lot's Mutex::lock, RwLock::read, and RwLock::write don't return Results, unlike the stdlib's.

Per c:78c6df9, the Guild::features structfield is no longer a Vec<Feature>. Discord adds guild features over time, which can cause guilds with those new features to fail in deserialization. Instead, we're future-proofing by making this a Vec<String>.

Per c:65e3279, the CreateEmbed builder's field and fields functions no longer take a builder as the argument, and instead take 3 arguments. For example, code like this:

channel.send_message(|m| m
    .embed(|e| e
        .title("This is an embed")
        .field(|f| f
            .name("Test field")
            .value("Test value")
            .inline(true))));

Would now be this:

channel.send_message(|m| m
    .embed(|e| e
        .title("This is an embed")
        .field("Test field", "Test value", true)))

Per c:ad0dcb3, shards can no longer have their afk property set, as this was a leftover from user account support. This removes the afk parameter of the Context::set_presence function, removal of the parameter from the Shard::set_presence function, and the Shard::set_afk function.

Per c:b328b3e, the client::EventHandler no longer prefixes all trait methods with on_. An implementation that looks like this:

use serenity::client::{Context, EventHandler};
use serenity::model::Message;

struct Handler;

impl EventHandler for Handler {
    fn on_message(&self, _: Context, msg: Message) {
        // ...
    }
}

Now looks like this:

use serenity::client::{Context, EventHandler};
use serenity::model::channel::Message;

struct Handler;

impl EventHandler for Handler {
    fn message(&self, _: Context, msg: Message) {
        // ...
    }
}

(a note on the serenity::model::channel::Message import later.)

Per c:b19b031, Client::new returns a Result, as it now creates some essential information on instantiation instead of deferring it to when a connection is started. You can probably just unwrap this Result.

Per c:b8efeaf, c:d5a9aa8, and c:65233ad, the client and gateway internals have been rebuilt to significantly reduce the number of atomic operations (upwards of ~85%). This means that retrieval of shard information (like the shard latency to the Discord gateway or the current connection status) are retrieved via the encompassing ShardManager located on the client. This can be inserted into the client's data structfield if you need to access that information in event or framework command handlers. See this example for more information. Additionally, Context::quit to shutdown the shard no longer exists; go through the ShardManager instead.

Per c:aad4744, the framework's Args::list function has been renamed to Args::multiple for consistency.

Per c:f10b9d7, c:1fd652b, c:0aa55a2, the framework has been reworked to be trait-based; thus as per c:f61816c, c:4e20277, allowed more useful functionality to commands.

Per c:05f6ed4, the client's close handle has been removed, in favour of doing so through the ShardManager.

Per c:8c9baa7, the Guild::default_message_notifications, Guild::mfa_level, PartialGuild::default_message_notifications, and PartialGuild::mfa_level structfields are now enums to represent a stronger type, instead of u64s.

Per c:bcd16dd, the model module has been broken up: instead of a giant root module full of imports, types have been moved to where they fit. For example, the Message, Reaction, and Channel structs are now in the model::channel module. The RichInvite, Member, Role, and MfaLevel types are now in model::guild. Refer to the commit message or the model module docs for more information.

Per c:be43836, the http::HttpError enum's InvalidRequest variant no longer gives just the HTTP status code of the response. It now includes the full Response instance.

Per c:2edba81, the builder re-export in the utils module no longer exists after being there in deprecation for a long time. Please import it like so:

// old
use serenity::utils::builder;

// new
use serenity::builder;

Added

Fixed

Changed

Misc.

0.4.5 - 2017-12-09

This release contains a hotfix for the hotfix release, as well as a slight behaviour change to the EditRole builder.

The last release contained a deserialization implementation fix which seemed to work after running tests, but it turns out that not all deserialization issues were fixed.

The EditRole builder's Default implementation no longer sets a value for each field, as this causes problems with stateless editing of roles.

Fixed

  • [model] Fix remaining deserializers c:52403a5

Changed

  • [builder] Remove EditRole::default implementation c:795eaa1

0.4.4 - 2017-12-09

This release contains a hotfix for snowflake deserialization on serde_json v1.0.8. Primary development is continuing on the v0.5.x branch and the library organization.

Fixed

  • [model] Fix snowflake deserializer c:77f462e

0.4.3 - 2017-11-01

This release contains bugfixes and marks the final release of the v0.4.x branch. Future development will continue on the v0.5.x branch.

Thanks to the following for their contributions:

Added

Changed

  • [model] Rename Guild::permissions_for to Guild::permissions_in, keep an alias (@zeyla) c:dcac271

Fixed

  • [model] Make Member::permissions return guild-level permissions (@zeyla) c:d3eddc6

Misc.

0.4.2 - 2017-10-29

This release contains the regular bugfixes, new features and slight behaviour changes.

Thanks to the following people for their contributions:

Added

Fixed

Changed

Misc.

0.4.1 - 2017-10-14

This release contains bugfixes and some newly added or newly exposed functionality.

Thanks to the following for their contributions this release:

Added

Fixed

Misc.

0.4.0 - 2017-09-25

This release contains a lot of added functionality, minor-scale rewrites, bugfixes, documentation work, and the beginning of a rewrite to use the tokio ecosystem.

The release was delayed due to a fairly majour bug in rust-websocket that we have forked over to temporarily fix.

This release was lead in development by @acdenisSK.

Thanks to the following for their contributions this release:

Upgrade Path

Per commits c:af1061b, c:cdedf36, and c:aa307b1, Direct Messaging other bot users is now disallowed by the API. To fix this, simply don't do it.

Per commit c:ebc4e51, deprecated functions were finally removed. The following can simply have their usage renamed:

  • Cache::get_channel --> Cache::channel
  • Cache::get_guild --> Cache::guild
  • Cache::get_guild_channel --> Cache::guild_channel
  • Cache::get_member --> Cache::member
  • Cache::get_private_channel --> Cache::private_channel
  • Cache::get_role --> Cache::role
  • Cache::get_user --> Cache::user
  • ChannelId::get_invites --> ChannelId::invites
  • ChannelId::get_message --> ChannelId::message
  • ChannelId::get_messages --> ChannelId::messages
  • ChannelId::get_reaction_users --> ChannelId::get_reaction_users
  • ChannelId::get_webhooks --> ChannelId::webhooks
  • Channel::get_message --> Channel::message
  • Channel::get_messages --> Channel::messages
  • Channel::get_reaction_users --> Channel::reaction_users
  • Client::login_bot --> Client::new
  • Client::login --> Client::new
  • Colour::get_b --> Colour::b
  • Colour::get_g --> Colour::g
  • Colour::get_r --> Colour::r
  • Colour::get_tuple --> Colour::tuple
  • CurrentUser::distinct --> CurrentUser::tag
  • Group::get_message --> Group::message
  • Group::get_messages --> Group::messages
  • Group::get_reaction_users --> Group::reaction_users
  • Guild::get_bans --> Guild::bans
  • Guild::get_channels --> Guild::channels
  • Guild::get_emoji --> Guild::emoji
  • Guild::get_emojis --> Guild::emojis
  • Guild::get_integrations --> Guild::integrations
  • Guild::get_invites --> Guild::invites
  • Guild::get_member --> Guild::member
  • Guild::get_members --> Guild::members
  • Guild::get_member_named --> Guild::member_named
  • Guild::get_prune_count --> Guild::prune_count
  • Guild::get_webhooks --> Guild::webhooks
  • GuildId::get_bans --> GuildId::bans
  • GuildId::get_channels --> GuildId::channels
  • GuildId::get_emoji --> GuildId::emoji
  • GuildId::get_emojis --> GuildId::emojis
  • GuildId::get_integrations --> GuildId::integrations
  • GuildId::get_invites --> GuildId::invites
  • GuildId::get_member --> GuildId::member
  • GuildId::get_members --> GuildId::members
  • GuildId::get_prune_count --> GuildId::prune_count
  • GuildId::get_webhooks --> GuildId::webhooks
  • Message::get_reaction_users --> Message::reaction_users
  • PartialGuild::get_bans --> PartialGuild::bans
  • PartialGuild::get_channels --> PartialGuild::channels
  • PartialGuild::get_emoji --> PartialGuild::emoji
  • PartialGuild::get_emojis --> PartialGuild::emojis
  • PartialGuild::get_integrations --> PartialGuild::integrations
  • PartialGuild::get_invites --> PartialGuild::invites
  • PartialGuild::get_member --> PartialGuild::member
  • PartialGuild::get_members --> PartialGuild::members
  • PartialGuild::get_prune_count --> PartialGuild::prune_count
  • PartialGuild::get_webhooks --> PartialGuild::webhooks
  • PrivateChannel::get_message --> PrivateChannel::message
  • PrivateChannel::get_messages --> PrivateChannel::messages
  • PrivateChannel::get_reaction_users --> PrivateChannel::reaction_users
  • Role::edit_role --> Role::edit
  • User::distinct --> User::tag

http::send_file has been replaced by http::send_files. Instead of using http::send_file like so:

use serde_json::Map;
use serenity::http;
use serenity::model::ChannelId;
use std::fs::File;

let channel_id = ChannelId(253635665344987136);
let filename = "mr-sakamoto.png";
let file = File::open(&format!("./img/{}", filename))?;
let map = Map::<String, Value>::new();

http::send_file(channel_id, file, filename, map)?;

Instead send an attachment of files, such as:

use serde_json::Map;
use serenity::http;
use serenity::model::ChannelId;
use std::fs::File;

let channel_id = ChannelId(253635665344987136);
let files = vec![
    (File::open(&format!("./img/{}", filename))?, filename),
];
let map = Map::<String, Value>::new();

http::send_files(channel_id, files, map)?;

Similar logic can be applied to shortcut methods which have been removed, namely:

  • Channel::send_file (instead use Channel::send_files)
  • ChannelId::send_file (instead use ChannelId::send_files)
  • Group::send_file (instead use Group::send_files)
  • GuildChannel::send_file (instead use GuildChannel::send_files)
  • PrivateChannel::send_file (instead use PrivateChannel::send_files)

Instead of using the now-removed Channel::delete_messages and Channel::delete_permission, use the inner channel's method:

use serenity::model::{Channel, ChannelId};

let channel = ChannelId(253635665344987136).get()?;
let message_ids = vec![
    MessageId(359845483356749825),
    MessageId(359854838403694592),
];

if let Channel::Guild(c) = channel {
    c.delete_messages(&message_ids)?;
}

Similar logic can be applied to Channel::delete_permission.

Member::find_guild ended up being only a shortcut to the Member::guild_id structfield. Instead of calling the find_guild method like member.find_guild(), instead access the structfield directly via member.guild_id.

The model::permissions::{general, text, voice} methods have been removed, as they ended up being shortcuts to the model::permissions::PRESET_GENERAL, model::permissions::PRESET_TEXT, and model::permissions::PRESET_VOICE constants, respectively.

Per commit c:ea432af, event handling is now done via implementing a trait. Instead of passing functions to the client directly like:

use serenity::Client;
use std::env;

let mut client = Client::new(env::var("DISCORD_TOKEN")?);

client.on_message(|ctx, msg| {
    // code
});

Instead implement the new EventHandler trait:

use serenity::client::{Client, Context, EventHandler};
use serenity::model::Message;

struct Handler;

impl EventHandler for Handler {
    fn on_message(&self, ctx: Context, msg: Message) {
        // code
    }
}

let client = Client::new(env::var("DISCORD_TOKEN")?);

Per commit c:4f2e47f, the deprecated ext module (which has recently only been a series of re-exports for the cache, framework, and voice modules) was removed. Instead of using serenity::ext::cache for example, use serenity::cache.

Per commit c:878684f, due to the concept of default channels being changed, GuildId::as_channel_id has been deprecated due to the fact that the ID of the default channel of a guild will no longer necessarily be the same as the guild's ID.

If you require this same exact functionality (the GuildId as a ChannelId), rewrite your code from:

use serenity::model::GuildId;

let channel_id = GuildId(81384788765712384).as_channel_id();

to:

use serenity::model::{ChannelId, GuildId};

let guild_id = GuildId(81384788765712384);
let channel_id = ChannelId(guild_id.0);

Per commits c:2b053ea, c:8cc2300, c:8e29694, and c:948b27c, custom frameworks can now be implemented, meaning that a built implementation is now passed instead of a base framework being provided and mutated. To use the old framework, modify code from:

use serenity::Client;
use std::env;

let mut client = Client::new(&env::var("DISCORD_TOKEN")?);

client.with_framework(|f| f
    // method calls to mutate framework here
);

to the new style:

use serenity::client::{Client, EventHandler};
use serenity::framework::standard::StandardFramework;
use std::env;

struct Handler;

impl EventHandler for Handler { }

let mut client = Client::new(&env::var("DISCORD_TOKEN")?, Handler);

client.with_framework(StandardFramework::new()
    // method calls here to mutate framework here
);

Per commit [c:fc9eba3d], if you were pattern matching on the serenity::framework::DispatchError::CheckFailed variant, instead either use or ignore the matched data by rewriting code from:

use serenity::framework::DispatchError;

// Code to begin dispatch error handling here.

match dispatch_error {
    DispatchError::CheckFailed => {
        // Handle operation here.
    },
    // Other variants.
}

to:

// The standard implementation is now in a "standard" framework module, but
// that's unrelated.
use serenity::framework::standard::DispatchError;

match dispatch_error {
    DispatchError::CheckFailed(_) => {
        // Handle operation here.
    },
    // Other variants.
}

Per commits c:45d72ef, c:03b6d78, and c:d35d719, the framework's command! macro no longer parses arguments' types for you. You are now given an Args struct that you can retrieve arguments from and parse from to a requested type that implements FromStr.

For example, a simple sum function that looked like:

#[macro_use] extern crate serenity;

command!(sum(_ctx, msg, _args, x: i64, y: i64) {
    let _ = msg.reply(&format!("Result: {}", x + y));
});

Now looks like:

use serenity::client::Context;
use serenity::framework::standard::Args;
use serenity::model::Message;

fn sum(_: &mut Context, msg: &Message, args: Args) -> Result<(), String> {
    let x = match args.single::<i64>() {
        Ok(x) => x,
        Err(_) => return Ok(()),
    };
    let y = match args.single::<i64>() {
        Ok(y) => y,
        Err(_) => return Ok(()),
    };

    let _ = msg.reply(&format!("Result: {}", x + y));
}

Per commit c:562ce49, serenity::model::User's FromStr implementation can now hit the REST API. No code changes required, but do note the possibility.

Per commit c:40031d9, the following routes have been removed for being userbot routes, which are leftovers from when serenity supported them and had them removed:

  • http::get_application_info
  • http::get_applications
  • http::get_emoji
  • http::get_emojis
  • model::Guild::emoji
  • model::Guild::emojis
  • model::GuildId::emoji
  • model::GuildId::emojis
  • model::PartialGuild::emoji
  • model::PartialGuild::emojis

Per commit c:092f288, bitflags has been upgraded, which introduces a minor change in how to use permissions.

Update code from:

use serenity::model::permissions::{ADD_REACTIONS, MANAGE_MESSAGES};

foo(vec![ADD_REACTIONS, MANAGE_MESSAGES]);

to:

use serenity::model::Permissions;

foo(vec![Permissions::ADD_REACTIONS, Permissions::MANAGE_MESSAGES]);

Added

Fixed

Changed

Misc.

0.3.0 - 2017-06-24

This release contains a number of added methods, fixes, deprecations, and documentation improvements. It brings a module restructure and an upgrade to rust-websocket v0.20, hyper v0.10, and switching to native-tls, meaning using an up-to-date rust-openssl v0.9 on Linux, schannel on Windows, and Secure Transport on Mac. The long-standing issue #56 was closed.

Thanks to the following for their contributions this release:

Upgrade Path

Invite retrieval functions now accept a stats argument. If you don't need stats, just pass false.

ChannelId::create_permission and GuildChannel::create_permission now accept a reference, as they do not need to own the overwrite.

The deprecated GuildChannel methods (get_invites, get_message, get_messages, get_reaction_users, get_webhooks) have been removed. Use their equivalents without the get_ prefix.

The send_file functions have been deprecated. Use send_files instead by passing a Vec.

CurrentUser::distinct and User::distinct have been deprecated. Instead use CurrentUser::tag and User::tag.

User::get has been deprecated. Instead, use UserId::get.

Role::edit_role has been deprecated, renaming it to Role::edit.

time has been removed as a direct dependency, moving to chrono. Public-facing fields that return time::Timespec or were a String in ISO-3339 format are now chrono::DateTime<UTC>s. Instead use its methods for what was being done with the Timespecs or strings.

User::direct_message and User::dm now accept a builder to allow for more complete, yet simple use out of the methods. Instead of passing a &str, use the provided builder:

// old
user.dm("hello")?;

// new
user.dm(|m| m.content("hello"))?;

Client::login has been deprecated. Instead use Client::new:

use serenity::Client;
use std::env;

// old
let client = Client::login(&env::var("DISCORD_TOKEN")?);

// new
let client = Client::new(&env::var("DISCORD_TOKEN")?);

Member::guild_id is now no longer an Option<GuildId> -- just a GuildId. Since this is now always present, Member::find_guild has been deprecated since the cache now never searches the cache for the guild ID.

The deprecated GuildChannel methods get_invites, get_message, get_messages, get_reaction_users, and get_webhooks have been removed. Use their alternatives, such as GuildChannel::invites, instead.

Added

Fixed

  • Don't skip @everyone role when checking channel overwrites (@Roughsketch) c:b468cbf
  • Allow unreachable_code lint in command! macro (@Flat) c:eb43b9c
  • Fix incorrect attempted send_file deserialization c:0102706
  • Fix ratelimits causing 429s in certain situations c:f695174
  • Check last heartbeat acknowledged in heartbeater c:ec9b1c7
  • Make client join shards and return c:175d3a3
  • Make client starts return an error c:858bbf2
  • Ws read/write timeout after 90s to avoid infinite blocking c:1700a4a
  • Fix negative nonces failing to deserialize c:d0b64cd
  • Use HTTPS Connector with remaining HTTP functions c:0d218e0 (@Roughsketch)

Changed

  • Restructure modules c:9969be6
  • Change create_permission to take a reference c:aea9885
  • Remove deprecated GuildChannel methods c:ab7f113
  • Guild::create_channel doesn't require mutability c:494cc50
  • Deprecate *User::distinct, add *User::tag c:6579b1f
  • Deprecate User::get c:afc571f
  • Deprecate Role::edit_role, add Role::edit c:c00f349
  • Switch to chrono c:990e611
  • Make User::direct_message/User::dm accept a builder c:11a02db
  • Deprecate Client::login, add Client::new c:7990381
  • Make Member::guild_id non-optional c:b4bd771
  • Remove Context::channel_id and Context::queue c:8b504ad
  • Make the framework's dynamic_prefix accept an &Message c:2845681
  • Deprecate Channel::delete_messages, Channel::delete_permission c:7fc49d8
  • Make Message::nonce a serde_json::Value c:c832009

Misc.

0.2.0 - 2017-05-13

This is a very large release with a number of rewritten components. The cache has been rewritten to make use of memory more efficiently, the models directory has been re-organized, structures are now deserialized via serde and serde_derive - instead of the custom decoding build script we had - with a number of bugfixes and other various changes and additions.

Thanks to the following for their contributions this release:

Upgrade Path

Replace uses of ext::cache::ChannelRef with model::Channel.

The following ext::cache::Cache method signatures are now encased in Arc<RwLock>s and should be handled appropriately:

  • call
  • channel
  • guild
  • guild_channel
  • group
  • member
  • role
  • user

Additionally, GuildId::find and UserId::find now return Option<Arc<RwLock>>s.

Member::display_name now returns a Cow<String> instead of a &str.

client::Context has had most of its methods removed. The methods were mostly a copy of those on ChannelId. Upgrade by instead calling methods on ChannelId:

command!(foo(ctx) {
    let _ = ctx.say("hello");
});

// is now written as:

command!(bar(_ctx, msg) {
    let _ = msg.channel_id.say("hello");
});

CreateMessage::nonce has been removed. Instead, simply do not provide a nonce.

ChannelId::edit_message now has an argument signature of:

&self, message_id: M, f: F
where F: FnOnce(CreateMessage) -> CreateMessage, M: Into<MessageId>

instead of

&self, message_id: M, text: &str, f: F
where F: FnOnce(CreateEmbed) -> CreateEmbed, M: Into<MessageId>

To account for this change, modify code like so:

channel_id.edit_message(message_id, "new content", |e| e);

// now:

channel_id.edit_message(message_id, |m| m.content("new content"));

Message::edit has also had an argument signature updated to:

&mut self, f: F where F: FnOnce(CreateMessage) -> CreateMessage

from:

&mut self, new_content: &str, embed: F where F: FnOnce(CreateEmbed) -> CreateEmbed

To account for this change, modify code like so:

message.edit("new content", |e| e.description("test"));

// now:

message.edit(|m| m.content("new content").embed(|e| e.description("test")));

client::rest::accept_invite, Invite::accept, and RichInvite::accept have been removed. Instead, do not attempt this, as they were userbot functions.

Selfbot support has been completely removed. Review the commit message for the long list of details.

Group calls and guild sync have also been removed. Read the commit message for all the details.

Instead of defining multiple separate error messages for command framework message dispatches, match the dispatch error in a single method:

// old code:
client.with_framework(|f| f
    .configure(|c| c
        .command_disabled_message("The command `%command%` was disabled")
        .blocked_guild_message("The owner of this guild has been blocked")
        .invalid_permission_message("You don't have permission to use this command")));

// new code:
client.with_framework(|f| f.on_dispatch_error(|_, msg, err| {
    match err {
        DispatchError::CommandDisabled(command_name) => {
            let _ = msg.channel_id.say(&format!("The command `{}` was disabled", command_name));
        },
        DispatchError::BlockedGuild => {
            // this change also allows for more intelligent error messages:
            if let Some(guild) = msg.guild() {
                let owner_id = guild.read().unwrap().owner_id;

                if let Some(user) = CACHE.read().unwrap().user(owner_id) {
                    let c = format!("The owner - {} - has been blocked", user.name);
                    let _ = msg.channel_id.say(&c);

                    return;
                }
            }

            let _ = msg.channel_id.say("The owner of this guild has been blocked");
        },
        DispatchError::LackOfPermissions(_) => {
            let _ = msg.channel_id.say("You don't have permission to use this command");
        },
    }
}));

All functions prefixed with get_ have had the prefix removed. For example, Guild::get_webhooks() is now Guild::webhooks().

Instead of using model::permissions::general(), model::permissions::text(), and model::permissions::voice(), use model::permissions::{PRESET_GENERAL, PRESET_TEXT, PRESET_VOICE}.

Added

Fixed

Changed

Misc.

0.1.5 - 2017-02-08

This is a release to fix broken nightly builds, due to a change in how rustc handles lifetimes, with a few performance optimizations and other fixes.

Upgrade Path

For Group::send_message, PrivateChannel::send_message, and GuildChannel::send_message, instead of passing in only a &str of content, use a CreateMessage builder:

// assuming a `channel` is bound

// old signature:
channel.send_message("hello");

// new signature:
channel.send_message(|m| m.content("hello"));

Instead of calling message_id.get_reaction_users and passing in a ChannelId, call channel_id.get_reaction_users and pass in the MessageId. Note that the latter already existed.

// assuming `channel_id`, `message_id`, and `reaction_type` are bound

// removed method:
message_id.get_reaction_users(channel_id, reaction_type, Some(10), None);

// alternative method:
channel_id.get_reaction_users(message_id, reaction_type, Some(10), None);

Added

  • Register the status user setting for user accounts (e.g. online, invisible) c:0b9bf91
  • Expose and document ratelimiting structures c:eb09f2d
  • Add method to EditGuild to transfer ownership c:f00e165

Fixed

  • Fix potential unreachable pattern warning in command! macro c:97f9bd1
  • Fix value of 'browser' in shard identify c:4cf8338
  • Remove lifetime on Search builder c:6f33a35

Changed

  • Standardize methods for creating messages c:c8c6b83
  • Remove MessageId::get_reaction_users c:268f356

Misc.

  • Avoid re-requesting the gateway URL when autosharding (optimization) c:e891ebe
  • Avoid cloning on non-framework message create events (opt.) c:b7cbf75
  • Avoid cloning the context on event dispatches (opt.) c:5ee5fef
  • Optimize presence update for current user in cache (opt.) c:9392f61
  • Make GLOBAL ratelimit mutex a unit (opt.) c:55ccaca
  • Resume when restarting WS sender/receiver c:04cfaa9

0.1.4 - 2017-01-26

This is a general release for pretty much everything, from new features to bugfixes to a switch to a more OOP style. The current minimum supported version is rustc 1.13+.

The next release will be v0.2.0, which will feature serde codegen support along with a rewrite of the framework. It will be a more modularized version of the library. v0.2.0 will require rustc 1.15+, due to the stabilization of Macros 1.1.

Thanks to the following for contributions this release:

Two of the major highlights of this release are that the broken pipe issue has been fixed, and the library is more OOP now and therefore no longer relies on the Context to get stuff done. The methods feature flag has been removed.

Upgrade Path

When formatting using Display for ChannelIds, RoleIds, and UserId, instead of formatting use their Mentionable equivilants:

use serenity::model::{ChannelId, RoleId, UserId};

// old
assert_eq!(format!("{}", ChannelId(1)), "<#1>");
assert_eq!(format!("{}", RoleId(2)), "<@&2>");
assert_eq!(format!("{}", UserId(3)), "<@3>");

// new
assert_eq!(format!("{}", ChannelId(1).mention()), "<#1>");
assert_eq!(format!("{}", RoleId(2)).mention()), "<@&2>");
assert_eq!(format!("{}", UserId(3).mention()), "<@3>");

When using EmbedBuilder::{image, thumbnail}, instead of calling another builder, provide urls directly:

use serenity::model::Embed;

// old
Embed::fake(|e| e
    .image(|i| i.url("https://not.zey.moe/me.png"))
    .thumbnail(|t| t.url("https://not.zey.moe/me2.png")));

// new
Embed::fake(|e| e
    .image("https://not.zey.moe/me.png")
    .thumbnail("https://not.zey.moe/me2.png"));

When specifying a sharding method, instead of passing a u8 for sharding info, pass a u64:

use serenity::Client;

let client = Client::login_bot(&env::var("DISCORD_TOKEN").unwrap());

// old
client.start_shard(1u8, 5u8); // or
client.start_shards(5u8); // or
client.start_shard_range([1u8, 3u8], 8u8);

// new
client.start_shard(1u64, 5u64); // or
client.start_shards(5u64); // or
client.start_shard_range([1u64, 3u64], 8u64);

Client.shards is now private. Instead of accessing it, don't.

When creating a Colour struct yourself, instead of specifying a single value field, pass a single tuple value:

use serenity::utils::Colour;

// old
Colour {
    value: 0,
}

// new
Colour(0);

Instead of using Attachment::download_to_directory to download an attachment to a directory, do it yourself:

use std::fs::File;
use std::io::Write;

// assuming an `attachment` has already been bound

// old
attachment.download_to_directory("./attachments");

// new
let bytes = attachment.download().unwrap();
let filepath: PathBuf = path.as_ref().join(&attachment.filename);
let mut f = File::create(&filepath);
let _ = f.write(&bytes);

Instead of calling Message::is_webhook():

// assuming a `message` has already been bound

// old
let _ = message.is_webhook();

// new
let _ = message.webhook_id.is_some();

Instead of PartialGuild::find_role(role_id):

use serenity::model::RoleId;

// assuming a `guild` has already been bound

// old
let _ = guild.find_role(RoleId(1));

// new
let _ = guild.roles.get(RoleId(1));

Instead of Guild::{get_channel, get_member}, call:

use serenity::model::{ChannelId, UserId};

// assuming a `guild` has already been bound

// old
let _ = guild.get_channel(ChannelId(1));
let _ = guild.get_member(UserId(2));

// new
let _ = guild.channels.get(ChannelId(1));
let _ = guild.members.get(UserId(2));

Instead of using Context methods, use their Id or other struct equivalents.

Added

  • the voice feature no longer requires the cache feature to be enabled c:7b45f16
  • the framework feature no longer requires the cache feature to be enabled c:86cd00f
  • Guild, InviteGuild, and PartialGuild now have splash_url methods c:d58c544
  • Expose Message::webhook_id for messages sent via webhooks (@fwrs) c:a2cbeb6
  • Framework: add option to ignore webhooks or DMs (@fwrs) c:8e2c052
  • Added documentation for creating embed timestamps (@foxbot) c:66546d3
  • Allow time::Tm to be passed into the embed timestamp field, in addition to a direct string c:b001234
  • Add Client::on_message() example (@indiv0) c:bcb70e8
  • Support webp/gif avatars/icons in URL methods c:ab778f8
  • Update current user presence in cache on set c:5b275fc
  • Add CurrentUser/User::static_avatar_url() methods to generate webp URLs c:c36841d
  • Command (batch) alias support (@fwrs) c:f96b6cc
  • Command example field for help command (@fwrs) c:f96b6cc
  • Added "Meibi Pink" to the Colour struct (@hsiW) c:2cb607d
  • Register support for 4011 code (too many shards) (@SunDwarf) c:93f3c60
  • Added "Rohrkatze Blue" to the Colour struct (@bippum) c:345e140
  • Add User::default_avatar_url() c:e85e901
  • Add Message::content_safe() to avoid @everyone/@heres (@fwrs) c:e5a83dd
  • Add Member::distinct(), User::distinct() (@fwrs) c:e5a83dd
  • Document that messages can't be older than 14 days when bulk deleting (@fwrs) c:0a2f5ab
  • Add shard latency tracking (stolen borrowed from brayzure/Eris) c:096b0f5
  • Add guild chunking c:3ca7ad9

Fixed

  • User::avatar_url no longer mentions the user in the generated URL c:0708ccf
  • Framework: owners_only check now functions only if the author of a message is an owner (@fwrs) c:6355288
  • Framework: fix command cooldown timer (would always say to wait i64::MAX seconds) c:fafa363
  • Framework: the before closure is now properly run when a message is sent by the owner c:760a47a
  • CurrentApplicationInfo now properly decodes due to flags no longer being sent c:2a743ce
  • Fix Message::delete() permission check c:4229034
  • Framework: properly split messages on character boundary limits; aka thanks Unicode c:c01f238
  • Remove need to import Context/Message in command macros (@acdenisSK) c:abd22d2
  • Fix a ton of gateway stuff [c:94fc85b], c:f894cfd, c:f894cfd
  • Specify command! macro signature as returning std::result::Result c:e9aae9c
  • Fix dependency description in example 06 (@DeltaEvo) c:92309b2
  • Return a User from rest::get_user -- not a CurrentUser c:f57a187
  • Fix shards always booting at index 0 c:83b29d5
  • Wait 5 seconds between shard boots to avoid session invalidations c:fb4d411
  • Use CDN for default avatars c:69ec62a
  • Fix Resumed event payload decoding c:c2e8b69
  • Fix CurrentApplicationInfo decoding without rpc_origins c:38db32e
  • Reboot shard on broken pipe; fixes a lot of gateway problems c:76f9095
  • Make rest::execute_webhook be a POST c:c050c59

Changed

  • Framework: argument number is now displayed on parsing error (@fwrs) c:fb07751
  • Id display formatters use the direct u64 instead of mentioning; format!("{}", UserId(7)) will format into "7" instead of "<@7>" c:933ee89
  • Default the framework's use_quotes for quote parsing to false (was true) c:38a484d
  • The CreateEmbed builder now has direct image and thumbnail methods instead of one-method builders c:68c473d
  • Accept u64 shard counts to allow using more than 255 shards (instead of u8s) c:ada07fa
  • Remove user logout endpoint c:70bf22a
  • Don't abuse unicode for message content sanitization (@fwrs) c:2b237e7
  • Change Colour struct to be a tuplestruct c:a8acd61
  • Make a single POST on guild role create c:147cf01
  • Switch to a mostly-fully OOP approach c:651c618
  • Rename webhooks methods to get_webhooks (eg: GuildChannel::webhooks() --> GuildChannel::get_webhooks()) c:e8a9086
  • Make Guild::create_channel and related functions return a GuildChannel c:5918d01

Misc.

  • Cleaned up YAML definition layouts c:00fb61b
  • Gateway identify compression code is now simplified c:2416813
  • Gateway Event decoders are now abstracted to individual struct implementations c:5fe6a39
  • Simplify Role's' Ord impl (@emoticon) c:6a887b2
  • Slightly simplify Shard::set_presence c:5c40e85
  • Rename repo references from serenity.rs to serenity (@fwrs) c:3348178
  • Simplify Reaction::delete() c:1594961
  • Abstract large threshold number to a constant c:f3f74ce
  • Avoid a needless string clone on login c:d3389be
  • Avoid a lot of Arc/Message/RwLock clones c:8c5ee70

0.1.3 - 2016-12-14

This is a hotfix for applying a PR and fixing a major bug in the plain help command.

Thanks to the following for contributions this release:

Upgrade Path

None.

Added

  • Blocking individual users and guilds in commands, add blocking commands, and configuring owners of bots (@fwrs) c:a39647d

Fixed

  • The plain help command now properly sends a message when requesting information about a command c:7b4b154

Misc.

  • Groups are now on their own lines in the plain help command c:16bd765

0.1.2 - 2016-12-14

This release focuses on revamping the framework, adding a large amount of configuration and overall features. v0.1.3 will be focused on performance optimizations and code cleanup.

Thanks to the following for contributions this release:

v0.1.2 can now be retrieved from the crates.io listing.

Upgrade Path

When using EmbedBuilder::{image, thumbnail}, instead of calling another builder, provide urls directly:

use serenity::model::Embed;

// old
Embed::fake(|e| e
    .image(|i| i.url("https://not.zey.moe/me.png"))
    .thumbnail(|t| t.url("https://not.zey.moe/me2.png")));

// new
Embed::fake(|e| e
    .image("https://not.zey.moe/me.png")
    .thumbnail("https://not.zey.moe/me2.png"));

Added

  • Allow mentionable structs to be used as command arguments (@fwrs) c:626ffb2
  • Implemented From<Embed> for CreateEmbed c:7914274
  • Framework command builder, quoted arguments, multi-prefixes (@fwrs) c:8f24aa3
  • {Emoji,EmojiIdentifier}::url c:ef6eba3
  • Command groups and buckets c:daf92ed

Fixed

Changed

  • Deprecate CreateEmbedImage::{height, width} and CreateEmbedThumbnail::{height, width}

Misc.

0.1.1 - 2016-12-05

v0.1.1 is a "features that v0.1.0 should have had" and "miscellaneous work" release. v0.1.2 will be focused on the framework, while v0.1.3 will be focused on performance optimizations.

Thanks to the following for contributions this release:

v0.1.1 can now be retrieved from the crates.io listing.

Upgrade Path

When calling rest::get_guilds, instead of passing no parameters, pass a GuildPagination variant and a limit:

use serenity::client::rest::{self, GuildPagination};
use serenity::model::GuildId;

// before
rest::get_guilds();

// after
rest::get_guilds(GuildPagination::After(GuildId(777)), 50);

Added

  • The following colours to the Colour struct:
  • Message::guild_id as a quick method for retrieving the Id of a message's guild c:bceb049
  • CurrentUser::guilds() to get the current user's guilds. Meant for use with selfbots c:57c060f
  • CurrentUser::edit() to edit the current user's profile settings c:16d1b3c
  • User::distinct to format a string with the username#discriminator combination (@fwrs) c:31becb1
  • Member::colour to retrieve the member's colour (@fwrs) c:43a5c5d
  • Roles can now be directly compared (role1 < role2) for hierarchy c:143337a
  • Documentation:
  • A custom shared state (not the Cache) can now be accessed and mutated across commands/contexts, through the use of Context.data's ShareMap. See example 06 for an example

Fixed

  • rest::start_integration_sync/Context::start_integration_sync now properly work (@abalabahaha) c:7f04179
  • Role positions can now be negative; fixes issues where a guild's @everyone role (and other roles) are negative c:f847638
  • Context::move_member's signature is now correct c:4de39da
  • The command! macro now publicly exports functions. This allows commands created via this macro to be separated into different modules or crates c:62ed564

Changed

  • rest::get_guilds now supports pagination of guilds, as the output is now limited to 100 c:57c060f

Misc.

  • Colour::dark_green is now sorted alphabetically (@khazhyk) c:4a14b92
  • Simplify the colour macro c:bb97211
  • Capitalize the hex value for Colour::blitz_blue ([@Kiseii]) [c:daa24ec]

0.1.0 - 2016-11-30

Initial commit.