Version 3.0.0 - Githubissues

Francessco121 commented 7 years ago

Discore v3 will be coming out within the next month so I figured now would probably be a good time to explain why the library is moving ahead a major version already :). Over the course of developing 2.x, many design issues have popped up. Mainly these are problems with how data is publicly exposed and how applications interact with Discord through the library - which would require many breaking changes to address.

This issue only details the major changes happening in v3, the smaller changes will all be documented on release (see below for the release plan). In addition, the 2.x documentation will also be archived and available on Discore's github.io site for anyone who needs them before upgrading. A migration guide for upgrading from 2.x will also be available on release (I hope to make this as painless as possible!).

The major changes

Discore from now on will only support bot users

After spending a great amount of time looking over the APIs available for Discord, it became clear that most if not all of the use cases for a library like Discore are bots. On top of this, Discord lacks a lot of documentation for using their WebSocket API for other purposes such as creating a custom client.

Luckily, this actually doesn't remove a lot of functionality from Discore. This change will remove the need to pass a DiscordBotUserToken (as this is the only option, so just a string is needed), which was the only existing authentication option anyway (unless you have a custom implementation of IDiscordAuthenticator). The only other change here is that data and operations that bots cannot use will be removed (e.g. ability to accept invites, the DiscordConnection entity).

In the long run, this change will keep Discore's focus set on creating amazing .NET Discord bots.

Overhauled WebSocket cache

Unfortunately, this change is going to break a lot of code - but I can promise it will be for the better and will actually simplify some code. The original cache had a single huge problem: some entities were stored hierarchically. For instance, to retrieve DiscordGuildMember's you would first need to grab the 'parent cache' DiscoreGuildCache. This created the need for a lot of boilerplate code just to interact with nested entities via the cache.

On top of it being a pain to use, this design also created some unfixable bugs. One of which came up in the issue #11: where user presence data would actually be dropped in cases where a guild is considered large. This occurred because the DiscoreMemberCache objects did not exist to hold the presence data.

Version 3.0 introduces a flattened cache, removing the need for objects such as DiscoreGuildCache and DiscoreMemberCache which will ultimately make Discore easier to use, and will allow the WebSocket implementation to be more flexible.

Instead of code looking like this:

if (cache.Guilds.TryGetValue(guildId, out DiscoreGuildCache guildCache))
{
    DiscordGuildMember member = guildCache.Members[userId].Value;
}

It will look something like:

DiscordGuildMember member = cache.GetGuildMember(guildId, userId);

Which is much more reasonable :).

Removal of DiscordHttpApplication and DiscordWebSocketApplication

Don't worry, you will still be able to use the two API sections independently! After using Discore for a while, it became very clear that these two classes are very unncessary and just end up coupling things together (for instance, WebSocket applications couple the HTTP API with the shard manager). To allow Discore to be used in a more flexible manner, both of these objects will be dropped.

To replace these, you will now be able to simply instantiate your own DiscordHttpClient as well as your own Shards (see next section) depending on your needs.

Removal of ShardManager

Similarly to the previous section, the ShardManager was also more of a burden than a help. It really wasn't "managing" anything and was just a container that also kept code coupled. With v3 you will be able to instantiate your own Shard instances and manage them however you want!

For instance if you are testing a bot and just need one shard, simply:

using (Shard shard = new Shard(token, 0, 1))
{
    await shard.StartAsync();

    // Good to go!
}

Release plan

Since v3 is bringing a lot of change, a pre-release version of v3 will be released to allow for adequate testing to be done myself and by anyone potentially interested. This should be out sometime mid-June. If all goes well, within the next 2 weeks (aiming for the end of June the latest) the stable version of v3 will be released.

Because v3 is going to take a decent amount of effort to upgrade to, version v2.4.0 will also be released around the same time v3 goes into pre-release. v2.4.0 will contain all of the non-breaking additions and bug fixes introduced in v3.

v3.0.0 project page. v2.4.0 project page.

Other thoughts

I really hate to introduce so many breaking changes, but this all does feel necessary for the future of Discore. Writing good Discord bots should be simple and this release will certainly put Discore on the right track for enabling this.

nvirm commented 7 years ago

Very nice to see such an extensive and thought out update, even though it will probably cause a bit of maintenance to existing solutions :+1: :)

Keep up the good work!

Francessco121 commented 7 years ago

Updated the original release plan: around the same time v3 goes into pre-release, version v2.4.0 will also be released. v2.4 will contain all of the non-breaking additions and bug fixes introduced in v3. This is to make sure that when v3 is stable, we can leave 2.x in a much stabler spot.