Add v1.1 migration documentation (#325)

* v1.1 migration documentation

* Resolve review feedback and reformat

* Resolve review feedback 2

docs/migration/v1.1.md

@@ -0,0 +1,128 @@
+# Migrate to v1.1
+
+When updating the SDK from version 1.0.z to 1.1.z you will need to make some changes to your code. This document
+explains the changes required to build your application again with the new SDK version.
+
+## Package name changes
+
+The SDK switched to Kotlin Multiplatform starting from v1.1. As a side effect some of our modules have been moved around
+or renamed.
+
+Each module now has separate builds for different platforms (common, jvm and android). Additionally the separate
+jellyfin-platform-android module was merged into jellyfin-core.
+
+The table below shows the new names to be used:
+
+| Module (before)               | Module (after)    |
+| ----------------------------- | ----------------- |
+| jellyfin-core                 | jellyfin-core     |
+| **jellyfin-platform-android** | **jellyfin-core** |
+| jellyfin-api                  | jellyfin-api      |
+| jellyfin-model                | jellyfin-model    |
+
+Gradle will automatically use the Android build when the Android plugin is enabled. If you need to explicitly use the
+Android build you can add the "-android" suffix.
+
+## SDK initialization
+
+The `Jellyfin {}` function to create an instance of the SDK was renamed to `createJellyfin {}`. The options set inside
+of this builder changed depending on your platform. If the settings are incorrect it will throw an exception on
+initialization.
+
+### JVM
+
+On the JVM there aren't many changes. Just make sure to rename `Jellyfin` to `createJellyfin`.
+
+```kotlin
+createJellyfin {
+	clientInfo = ClientInfo(name = "My awesome client!", version = "1.33.7")
+}
+```
+
+### Android
+
+No longer needs the `android()` function called as this is automatically applied. Instead, set the context variable to
+an Android context.
+
+```kotlin
+createJellyfin {
+	context = /* Android Context */
+	clientInfo = ClientInfo(name = "My awesome client!", version = "1.33.7")
+}
+```
+
+## API extensions
+
+API interaction was improved for better performance and to make it easier to use. Previously when using the API you
+had to follow two steps:
+
+1. Create API client instance using `jellyfin.createApi`
+2. Create instance of an API class that contains operations, like UserApi.
+
+This came with a few issues. First, you had to keep track of those API classes to avoid constantly creating new ones.
+Secondly, you couldn't use autocomplete in an IDE to easily find the available API classes and had to rely on
+api.jellyfin.org.
+
+The old behavior still exists in v1.1, and the new behavior actually relies on it. You can now use extension properties
+to get an API instance stored in the API client. A short example follows:
+
+```kotlin
+val api = jellyfin.createApi(/* ... */)
+
+// Old
+val userApi = UserApi(api)
+
+// New
+val userApi = api.userApi 
+```
+
+The extension properties should be imported, an IDE will do this automatically. The API class is initialized on first
+use and stored in the API client.
+
+## Collections in the API
+
+Previously when using collections in the parameters or request bodies of operations you had to use an instance of
+`List`. Starting from v1.1 the types have changed to `Collection`. This means you can use a `Set` or any other type that
+implements Collection.
+
+## Error reporting in RecommendedServerDiscovery
+
+The RecommendedServerDiscovery class (`jellyfin.discovery.getRecommendedServers(candidates)`) is a powerful tool to
+correct user inputted server addresses and find a SDK compatible server. One issue we've observed in the Jellyfin
+Android apps was that it lacked information as to why a server was not recommended if the input is correct. To fix this
+a part of the algorithm was rewritten to report issues. If you're using this function you can now use the newly added
+`issues` collection added to the returned `RecommendedServerInfo`. We currently have the following issues:
+
+- MissingSystemInfo(throwable: Throwable?)
+
+  No system information found. This could happen due too networking issues or an invalid server address.
+
+- InvalidProductName(productName: String?)
+
+  The product name in the system information is incorrect.
+
+- MissingVersion
+
+  No version found in system information.
+
+- UnsupportedServerVersion(public val version: ServerVersion)
+
+  The SDK does not support the server version.
+
+- OutdatedServerVersion(version: ServerVersion)
+
+  The SDK uses a newer version of the API compared to the server. While this normally shouldn't be a problem, it may
+  potentially cause problems like crashes.
+
+- SlowResponse(responseTime: Long)
+
+  The system information response was slow.
+
+## Replacing KtorClient 
+
+This version of the SDK changed how the backend of the API part works. Previously the `createApi` function would return
+a `KtorClient` instance and you might have used this type in your code. Starting from v1.1 it is strongly advised to
+instead use the `ApiClient` interface type.
+
+The SDK now supports different ApiClient implementations. An ApiClient is used to handle the HTTP part while serializing
+and creating models is done by the SDK. We might replace KtorClient in the future or add different implementations.