Draft of migration guide

Author: DenTelezhkin

Docs/1.0 Migration Guide.md

@@ -1 +1,137 @@
 # TRON 1.0 Migration Guide
+
+## Wrapping Alamofire
+
+Starting from the beginning, `TRON` was a wrapper around [Alamofire](https://github.com/Alamofire/Alamofire). In 0.x releases we tried to hide this fact behind our own constructs and API facade. Basically, we took similar approach to [Moya](https://github.com/Moya/Moya) framework. And while usually completely hiding implementation details from the client is a good idea, we no longer feel it's viable in this current case.
+
+The benefits of facade approach is understandable - you need to only study one framework instead of two. However facade leads to several problems, here are some of them:
+
+#### Code duplication
+
+To completely hide implementation details from the client, you need to provide your own abstractions, that are basically copies of internal framework, for example, here's [some code from Moya](https://github.com/Moya/Moya/blob/72251f8910071568c626a61ad587367a1afb1e49/Source/Moya.swift#L8-L10). HTTP methods that we all know, are basically a duplicated enum from Alamofire, that can be easily removed.
+
+#### Incomplete functionality
+
+API facade is somewhat limited in terms of functionality. It's hard to wrap every single piece of Alamofire. And there's functionality, for example multipart upload, that heavily uses Alamofire data structures and therefore is very hard to implement in API facade. This is probably one of the reasons multipart upload takes a **year** [to implement](https://github.com/Moya/Moya/issues/114) in Moya. And when Alamofire introduces new feature, it takes even longer to port it to a wrapper.
+
+#### Hard customization
+
+Using facade sometimes locks you into artificial barriers that are created only to prevent you from knowing that you are using Alamofire. For example, there's a feature on Alamofire.Request, that allows you to print it's cURL to console using debugDescription variable. However, if used through API facade, you no longer know that you are using Alamofire.Request, then how do you allow using such feature without major headaches?
+
+### Our solution
+
+Starting with 1.0 release, we no longer hide Alamofire.Request from developer. So now, you can do this:
+
+```swift
+request.perform(success: { result in })?.responseString { string in
+    print(string)
+}.progress { bytesWritten, totalBytesWritten, totalBytesExpectedToWrite in
+    print(bytesWritten, totalBytesWritten, totalBytesExpectedToWrite)
+}
+```
+
+`RequestToken` protocol is removed, all perform request method return Alamofire.Request?, which will be nil in case request was stubbed.
+
+Previously, progress closure was included into `MultipartAPIRequest` `perform` method. Now, since it's available on returned Alamofire.Request property, method is reworked:
+
+```
+// Old:
+let request : MultipartAPIRequest<User,MyAppError> = tron.multipartRequest(path: "profile")
+multipartRequest.appendMultipartData(data, name: "avatar", filename: "avatar.jpg", mimeType: "image/jpeg")
+request.performWithSuccess({ user in
+    print("user avatar updated!")
+  },
+  failure: { error in
+    print("failed to upload user avatar")
+  },
+  progress: { progress in
+    print("Picture is uploading, progress: \(CGFloat(progress.totalBytesWritten) / CGFloat(progress.totalBytesExpectedToWrite))")
+  })
+  
+// New:
+let request: MultipartAPIRequest<User,MyAppError> = tron.uploadMultipart(path: "profile") { formData in 
+    formData.appendBodyPart(data: data,name: "avatar", mimeType: "image/jpeg")
+}
+request.performMultipart(success: { user in 
+    print("user avatar updated!")
+  },
+  failure: { error in
+    print("failed to upload user avatar")
+  }, encodingCompletion: { completion in
+    if case let Manager.MultipartFormDataEncodingResult.Success(request,_,_) = completion {
+        request.progress { _, totalBytesWritten, totalBytesExpectedToWrite in
+            print("Picture is uploading, progress: \(CGFloat(totalBytesWritten) / CGFloat(totalBytesExpectedToWrite))")
+        }
+    }
+})
+```
+
+## New features
+
+We are committed to providing all features Alamofire has to the framework user, and wrapping them into our convenience structures. 1.0 release has full support for download and upload tasks:
+
+#### Upload
+
+From file:
+
+* From file:
+
+```swift
+let request = tron.upload(path: "photo", file: fileUrl)
+```
+
+* NSData:
+
+```swift
+let request = tron.upload(path: "photo", data: data)
+```
+
+* Stream:
+
+```swift
+let request = tron.upload(path: "photo", stream: stream)
+```
+
+#### Download
+
+```swift
+let request = tron.download(path: "file", destination: destination)
+```
+
+Resume downloads:
+
+```swift
+let request = tron.download(path: "file", destination: destination, resumingFromData: data)
+```
+
+#### Performing uploads and downloads
+
+All downloads and uploads(except for multipart) use the same `APIRequest` method:
+
+```swift
+request.perform(success: { result in }, failure: { error in })
+```
+
+Old `performWithSuccess(_:failure:)` method is deprecated and will be removed in future releases.
+
+#### Perform with completion block
+
+Since we no longer hide Alamofire from developer, we are now able to provide perform method with Alamofire completion block, which can be used in several useful ways, for example observing request timeline:
+
+```swift
+request.perform(completion: { response in 
+    print(response.result) // Alamofire.Result
+    print(response.timeline) // Alamofire.Timeline
+    print(response.response) // NSHTTPURLResponse?
+})
+```
+
+### Miscellaneous API improvements
+
+Previously, `MultipartAPIRequest` was a subclass of `APIRequest`, which allowed to define it's variable as `APIRequest`, and potentially could lead to runtime crash with improper use. Now, both `MultipartAPIRequest` and `APIRequest` subclass `BaseRequest`, thus preventing this use case.
+
+`Progress` and `ProgressClosure` typealiases are removed, since `TRON` framework no longer handles any progress closures.
+
+`EventDispatcher` class, `TRON.dispatcher` and `APIRequest.dispatcher` properties are replaced with `processingQueue` and `resultDeliveryQueue` properties on `TRON` and `APIRequest`. `processingQueue` property determines on which queue should response parsing proceed, and `resultDeliveryQueue` determines on which queue completion blocks should be called.
+
+`RxSwift` extension `rxMultipartResult()` method on `MultipartAPIRequest` now returns Observable<ModelType> instead of tuple of observables.