Include Documentation for Migrating from 0.9.x to 1.0

docs/api/.gitignore

@@ -3,3 +3,4 @@
 #  temp file  #
 ###############
 *.yml
+.manifest

docs/docfx.json

@@ -65,6 +65,9 @@
     "template": [
       "default"
     ],
+    "globalMetadata": {
+      "_appFooter": "Discord.Net (c) 2015-2016"
+    },
     "noLangKeyword": false
   }
 }

docs/guides/samples/migrating/event.cs

@@ -0,0 +1,4 @@
+_client.MessageReceived += async (msg) =>
+{
+    await msg.Channel.SendMessageAsync(msg.Content);
+}

docs/guides/samples/migrating/sync_event.cs

@@ -0,0 +1,5 @@
+_client.Log += (msg) =>
+{
+    Console.WriteLine(msg.ToString());
+    return Task.CompletedTask;
+}

docs/guides/terminology.md

@@ -1,3 +1,8 @@
+---
+uid: Terminology
+title: Terminology
+---
+
 # Terminology
 
 ## Preface

docs/migrating.md

@@ -0,0 +1,81 @@
+# Migrating from 0.9
+
+**1.0.0 is the biggest breaking change the library has gone through, do to massive
+changes in the design of the library.**
+
+>A medium to advanced understanding is recommended when working with this library.
+
+One of the biggest major changes from `0.9.x` is the exclusive use of interfaces.
+For the most part, your usability will be very similar to the 0.9 approach of concrete
+classes. You **will** be required to cast some entities; this is outlined in a later
+section.
+
+It is recommended to familiarize yourself with the entities in 1.0 before continuing. 
+Feel free to look through the library's source directly, look through IntelliSense, or 
+look through our hosted [API Documentation](xref:Discord).
+
+## Entities 
+
+Most API models function _similarly_ to 0.9, however their names have been changed. 
+You should also keep in mind that we now separate different types of Channels and Users.
+
+Take a look at inheritance section of @Terminology for an example of how inheritance and interfaces
+work in 1.0
+
+Below is a table that compares most common 0.9 entities to their 1.0 counterparts.
+
+>This should be used mostly for migration purposes. Please take some time to consider whether
+>or not you are using the right "tool for the job" when working with 1.0
+
+| 0.9 | 1.0 | Notice |
+| --- | --- | ------ |
+| Server | @Discord.IGuild |
+| Channel | @Discord.IGuildChannel | Applies only to channels that are members of a Guild |
+| Channel.IsPrivate | @Discord.IDMChannel
+| ChannelType.Text | @Discord.ITextChannel | This applies only to Text Channels in Guilds
+| ChannelType.Voice | @Discord.IVoiceChannel | This applies only to Voice Channels in Guilds
+| User | @Discord.IGuildUser | This applies only to users belonging to a Guild*
+| Profile | @Discord.ISelfUser
+| Message | @Discord.IMessage
+
+\* To retrieve an @Discord.IGuildUser, you must retrieve the user from an @Discord.IGuild.
+[IDiscordClient.GetUserAsync](xref:Discord.IDiscordClient#Discord_IDiscordClient_GetUserAsync_System_UInt64_) 
+returns a @Discord.IUser, which only contains the information that Discord exposes for public users.
+
+## Event Registration
+
+Prior to 1.0, events were registered using the standard c# `Handler(EventArgs)` pattern. In 1.0,
+events are delegates, but are still registered the same.
+
+For example, let's look at [DiscordSocketClient.MessageReceived](xref:Discord.WebSocket.DiscordSocketClient#Discord_WebSocket_DiscordSocketClient_MessageReceived)
+
+To hook an event into MessageReceived, we now use the following code:  
+[!code-csharp[Event Registration](guides/samples/migrating/event.cs)]
+
+> **All Event Handlers in 1.0 MUST return Task!**
+
+If your event handler is marked as `async`, it will automatically return `Task`. However,
+if you do not need to execute asynchronus code, do _not_ mark your handler as `async`, and instead,
+stick a `return Task.CompletedTask` at the bottom.
+
+[!code-csharp[Sync Event Registration](guides/samples/migrating/sync_event.cs)]
+
+**Event handlers no longer require a sender.** The only arguments your event handler needs to accept
+are the parameters used by the event. It is recommended to look at the event in IntelliSense or on the
+API docs before implementing it.
+
+## Async
+
+Nearly everything in 1.0 is an async Task. You should always await any tasks you invoke.
+
+However, when using WebSockets, you may find this both inconvienent, and unnecessary, as many of the
+WebSocket implementations of the interfaces keep their own local cache of objects, rendering the use
+of async redundant. 
+
+**As of right now,** there are extension methods you can use, located in `Discord.WebSocket` that will
+provide java-esque, synchronus `GetXXX` methods to replace the asynchronus methods on WebSocket entities.
+
+This functionality may be changed at a later date, we are currently reviewing this implementation and
+alternative methods.
+
+For your reference, you may want to look through the extension classes located in @Discord.WebSocket

docs/toc.yml

@@ -1,6 +1,8 @@
 
 - name: Guides
   href: guides/
+- name: Migrating
+  href: migrating.md
 - name: API Documentation
   href: api/
   homepage: api/index.md