Update UPGRADING document for v1.5.0 release.

UPGRADING.md

@@ -1,12 +1,145 @@
-### Upgrading to v.1.4.0
+### Upgrading to v1.5.0
+
+#### ASM v0.10.x support added, v0.9.x support dropped
+
+[ASM](https://github.com/rails-api/active_model_serializers) introduced
+breaking changes with ASM v0.10.x. Support has been introduced in v1.5.0.
+If you require support for older version of ASM, please lock your Gemfile
+to the relevant version.
+
+#### Non-collection Serializer Resolution
+
+Serializer resolution now uses the following strategy:
+
+1. Defined by the resource
+
+```
+class UsersApi < Grape::Api
+  resource :users do
+    get '/:id', serializer: SpecifiedUserSerializer do
+      current_user
+    end
+  end
+end
+
+class User
+  def serializer_class
+    SpecifiedUserSerializer
+  end
+end
+```
+
+2. Specified by options
+
+```
+class UsersApi < Grape::Api
+  resource :users do
+    get '/:id', serializer: SpecifiedUserSerializer do
+      current_user
+    end
+  end
+end
+```
+
+2. Namespace inferred
+
+```
+class V1::UsersApi < Grape::Api
+  resource :users do
+    get '/:id' do
+      current_user
+    end
+  end
+end
+# 'V1::UsersApi'.deconstantize => 'V1'
+# searches for serializers in the V1:: namespace with the name UserSerializer
+
+# used
+class V1::UserSerializer
+  ...
+end
+
+# not used since V1::UserSerializer resolved first
+class UserSerializer
+  ...
+end
+```
+
+3. Version inferred
+
+```
+class UsersApi < Grape::Api
+  version 'v2'
+
+  resource :users do
+    get '/:id' do
+      current_user
+    end
+  end
+end
+# 'v2'.classify => V2
+# searches for serializers in the V2:: namespace with the name UserSerializer
+
+# used
+class V2::UserSerializer
+  ...
+end
+
+# not used since V2::UserSerializer resolved first
+class UserSerializer
+  ...
+end
+```
+
+4. Default ASM lookup
+
+```
+class V1::UsersApi < Grape::Api
+  version 'v2'
+
+  resource :users do
+    get '/:id' do
+      current_user
+    end
+  end
+end
+# searches for serializers in the V1:: namespace, none found
+# searches for serializers in the V2:: namespace, none found
+
+# used as no other serializers were found
+class UserSerializer
+  ...
+end
+```
+
+#### Collection Serializer Resolution
+
+Serializer resolution for collections also uses the above strategy, but has
+the added option of overriding the member serializer if the `each_serializer`
+options is specified.
+
+```
+class UsersApi < Grape::Api
+  resource :users do
+    get each_serializer: SpecifiedUserSerializer do
+      User.all
+    end
+  end
+end
+```
+
+
+### Upgrading to v1.4.0
 
 #### Changes in Serializer Namespacing
 
-Version 1.4.0 introduced changes in serializer namespacing when using Grape API versioning.
+Version 1.4.0 introduced changes in serializer namespacing when using Grape
+API versioning.
 
 If you haven't declared an API version in Grape, nothing changed.
 
-If your Grape API is versioned, which means you have declared at least one version in Grape, you must namespace your serializers accordingly.
+If your Grape API is versioned, which means you have declared at least one
+version in Grape, you must namespace your serializers accordingly.
 
 For example, given the following API.
 
@@ -48,7 +181,8 @@ module Chocolate
 end
 ```
 
-This will allow you to keep your serializers easier to maintain and more organized.
+This will allow you to keep your serializers easier to maintain and more
+organized.
 
 ```
 app
@@ -73,13 +207,15 @@ or alternatively:
     └── candy_bar_user_serializer.rb
 ```
 
-Thus, ActiveModelSerializer will fetch automatically the right serializer to render.
+Thus, ActiveModelSerializer will fetch automatically the right serializer to
+render.
 
 ### Upgrading to v1.0.0
 
 #### Changes to Array Roots
 
-When serializing an array, the array root is set to the innermost namespace name if there is one, otherwise it is set to the route name.
+When serializing an array, the array root is set to the innermost namespace
+name if there is one, otherwise it is set to the route name.
 
 In the following example the array root is `users`.