<commit_before>[Back to Guides](../README.md)

# How to migrate from `0.8` to `0.10` safely

## Disclaimer
### Proceed at your own risk
This document attempts to outline steps to upgrade your app based on the collective experience of
developers who have done this already. It may not cover all edge cases and situations that may cause issues,
so please proceed with a certain level of caution.

## Overview
This document outlines the steps needed to migrate from `0.8` to `0.10`. The method described
below has been created via the collective knowledge of contributions of those who have done
the migration successfully. The method has been tested specifically for migrating from `0.8.3`
to `0.10.2`.

The high level approach is to upgrade to `0.10` and change all serializers to use
a backwards-compatible `ActiveModel::V08::Serializer`or `ActiveModel::V08::CollectionSerializer`
and a `ActiveModelSerializers::Adapter::V08Adapter`. After a few more manual changes, you should have the same
functionality as you had with `AMS 0.8`. Then, you can continue to develop in your app by creating
new serializers that don't use these backwards compatible versions and slowly migrate
existing serializers to the `0.10` versions as needed.

### `0.10` breaking changes
- Passing a serializer to `render json:` is no longer supported

```ruby
render json: CustomerSerializer.new(customer) # rendered in 0.8, errors in 0.10
```

- Passing a nil resource to serializer now fails

```ruby
CustomerSerializer.new(nil) # returned nil in 0.8, throws error in 0.10
```

- Attribute methods are no longer defined on the serializer, and must be explicitly
  accessed through `object`

```ruby
class MySerializer
  attributes :foo, :bar

  def foo
    bar + 1 # bar does not work, needs to be object.bar in 0.10
  end
end
```

 - `root` option to collection serializer behaves differently

```ruby
# in 0.8
ActiveModel::ArraySerializer.new(resources, root: "resources")
# resulted in { "resources": <serialized_resources> }, does not work in 0.10
```

- No default serializer when serializer doesn't exist
- `@options` changed to `instance_options`

## Steps to migrate

### 1. Upgrade the `active_model_serializer` gem in you `Gemfile`
Change to `gem 'active_model_serializers', '~> 0.10'` and run `bundle install`

### 2. Add `ActiveModel::V08::Serializer`

```ruby
module ActiveModel
  module V08
    class Serializer < ActiveModel::Serializer<commit_msg>Update upgrade_from_0_8_to_0_10.md (#1933)<commit_after>[Back to Guides](../README.md)

# How to migrate from `0.8` to `0.10` safely

## Disclaimer
### Proceed at your own risk
This document attempts to outline steps to upgrade your app based on the collective experience of
developers who have done this already. It may not cover all edge cases and situations that may cause issues,
so please proceed with a certain level of caution.

## Overview
This document outlines the steps needed to migrate from `0.8` to `0.10`. The method described
below has been created via the collective knowledge of contributions of those who have done
the migration successfully. The method has been tested specifically for migrating from `0.8.3`
to `0.10.2`.

The high level approach is to upgrade to `0.10` and change all serializers to use
a backwards-compatible `ActiveModel::V08::Serializer`or `ActiveModel::V08::CollectionSerializer`
and a `ActiveModelSerializers::Adapter::V08Adapter`. After a few more manual changes, you should have the same
functionality as you had with `AMS 0.8`. Then, you can continue to develop in your app by creating
new serializers that don't use these backwards compatible versions and slowly migrate
existing serializers to the `0.10` versions as needed.

### `0.10` breaking changes
- Passing a serializer to `render json:` is no longer supported

```ruby
render json: CustomerSerializer.new(customer) # rendered in 0.8, errors in 0.10
```

- Passing a nil resource to serializer now fails

```ruby
CustomerSerializer.new(nil) # returned nil in 0.8, throws error in 0.10
```

- Attribute methods are no longer defined on the serializer, and must be explicitly
  accessed through `object`

```ruby
class MySerializer
  attributes :foo, :bar

  def foo
    bar + 1 # bar does not work, needs to be object.bar in 0.10
  end
end
```

 - `root` option to collection serializer behaves differently

```ruby
# in 0.8
ActiveModel::ArraySerializer.new(resources, root: "resources")
# resulted in { "resources": <serialized_resources> }, does not work in 0.10
```

- No default serializer when serializer doesn't exist
- `@options` changed to `instance_options`
- Nested relationships are no longer walked by default. Use the `:include` option at **controller `render`** level to specify what relationships to walk. E.g. `render json: @post, include: {comments: :author}` if you want the `author` relationship walked, otherwise the json would only include the post with comments. See: https://github.com/rails-api/active_model_serializers/pull/1127
- To emulate `0.8`'s walking of arbitrarily deep relationships use: `include: '**'`. E.g. `render json: @post, include: '**'`

## Steps to migrate

### 1. Upgrade the `active_model_serializer` gem in you `Gemfile`
Change to `gem 'active_model_serializers', '~> 0.10'` and run `bundle install`

### 2. Add `ActiveModel::V08::Serializer`

```ruby
module ActiveModel
  module V08
    class Serializer < ActiveModel::Serializer
{'fraction_non_alphanumeric': 0.09040590405904059, 'fraction_numerical': 0.025645756457564575, 'mean_word_length': 4.706315789473684, 'pattern_counts': {'":': 2, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '234984', 'n_tokens_mistral': 1598, 'n_tokens_neox': 1474, 'n_words': 706}