active_model_serializers 0.10.0 → 0.10.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eb97c8740c2530c085ee9186ea27ddd220367fc3
-  data.tar.gz: 0a768d3ab122abe2c3e7f5b6c00a8dada6872433
+  metadata.gz: c59f59688a0f1097d51eecd56caa45fc9ccec6e0
+  data.tar.gz: 5907cb2c75b806f2ac46b9457a33e898d10dc4a1
 SHA512:
-  metadata.gz: 5589022dd6fa160c0a03981cedf46433fb1eb19e4bac5f3489908671e9e0969c48bb7a86cf03d12cf8ce825b2efe3ed6ad1b6594019635470319c899e7964617
-  data.tar.gz: 989cf413780f12d47a553a7aae5cba33de1625bbc022366b7e4533810b87b151302ed6000116c03234bf2b2048a913048624728a54be87cead848076924cf6ce
+  metadata.gz: 540883101bd1555c3697cae38658e773c726a42d8195d6f9f59f928cfe3bf5105c91f3c8fd48c88e83e4d2f288ebd03b07f74d9747ca66fc281d50f82b2983eb
+  data.tar.gz: 208b3eb1c115cb2c18dce647371e9748576bee1a440c4e7b9edc1e5730e145096bb722c999cd37b620fe03b306dde0da012799d092e11c6377bd1a2c14e990b2

data/.rubocop.yml

@@ -1,7 +1,5 @@
-inherit_from: .rubocop_todo.yml
-
 AllCops:
-  TargetRubyVersion: 2.2
+  TargetRubyVersion: 2.1
   Exclude:
     - config/initializers/forbidden_yaml.rb
     - !ruby/regexp /(vendor|bundle|bin|db|tmp)\/.*/
@@ -46,7 +44,7 @@ Style/AlignParameters:
   EnforcedStyle: with_fixed_indentation
 
 Style/ClassAndModuleChildren:
-  EnforcedStyle: compact
+  EnforcedStyle: nested
 
 Style/Documentation:
   Enabled: false

data/.travis.yml

@@ -20,13 +20,15 @@ cache:
 
 script:
   - bundle exec rake ci
-
+after_success:
+  - codeclimate-test-reporter
 env:
   global:
     - "JRUBY_OPTS='--dev -J-Xmx1024M --debug'"
   matrix:
     - "RAILS_VERSION=4.1"
     - "RAILS_VERSION=4.2"
+    - "RAILS_VERSION=5.0"
     - "RAILS_VERSION=master"
 
 matrix:
@@ -37,6 +39,12 @@ matrix:
     env: RAILS_VERSION=master
   - rvm: jruby-head
     env: RAILS_VERSION=master
+  - rvm: 2.1
+    env: RAILS_VERSION=5.0
+  - rvm: jruby-9.0.4.0
+    env: RAILS_VERSION=5.0
+  - rvm: jruby-head
+    env: RAILS_VERSION=5.0
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head

data/CHANGELOG.md

@@ -1,8 +1,86 @@
 ## 0.10.x
 
-### [master (unreleased)](https://github.com/rails-api/active_model_serializers/compare/v0.10.0...master)
+### [master (unreleased)](https://github.com/rails-api/active_model_serializers/compare/v0.10.3...master)
 
-### v0.10.0 (2016-05-17)
+Breaking changes:
+
+Features:
+
+Fixes:
+
+Misc:
+
+### [v0.10.3 (2016-11-21)](https://github.com/rails-api/active_model_serializers/compare/v0.10.2...v0.10.3)
+
+Fixes:
+
+- [#1973](https://github.com/rails-api/active_model_serializers/pull/1973) Fix namespace lookup for collections and has_many relationships (@groyoh)
+- [#1887](https://github.com/rails-api/active_model_serializers/pull/1887) Make the comment reflect what the function does (@johnnymo87)
+- [#1890](https://github.com/rails-api/active_model_serializers/issues/1890) Ensure generator inherits from ApplicationSerializer when available (@richmolj)
+- [#1922](https://github.com/rails-api/active_model_serializers/pull/1922) Make railtie an optional dependency in runtime (@ggpasqualino)
+- [#1930](https://github.com/rails-api/active_model_serializers/pull/1930) Ensure valid jsonapi when relationship has no links or data (@richmolj)
+
+Features:
+
+- [#1757](https://github.com/rails-api/active_model_serializers/pull/1757) Make serializer lookup chain configurable. (@NullVoxPopuli)
+- [#1968](https://github.com/rails-api/active_model_serializers/pull/1968) (@NullVoxPopuli)
+  - Add controller namespace to default controller lookup
+  - Provide a `namespace` render option
+  - document how set the namespace in the controller for implicit lookup.
+- [#1791](https://github.com/rails-api/active_model_serializers/pull/1791) (@bf4, @youroff, @NullVoxPopuli)
+  - Added `jsonapi_namespace_separator` config option.
+- [#1889](https://github.com/rails-api/active_model_serializers/pull/1889) Support key transformation for Attributes adapter (@iancanderson, @danbee)
+- [#1917](https://github.com/rails-api/active_model_serializers/pull/1917) Add `jsonapi_pagination_links_enabled` configuration option (@richmolj)
+- [#1797](https://github.com/rails-api/active_model_serializers/pull/1797) Only include 'relationships' when sideloading (@richmolj)
+
+Fixes:
+
+- [#1833](https://github.com/rails-api/active_model_serializers/pull/1833) Remove relationship links if they are null (@groyoh)
+- [#1881](https://github.com/rails-api/active_model_serializers/pull/1881) ActiveModelSerializers::Model correctly works with string keys (@yevhene)
+
+Misc:
+- [#1767](https://github.com/rails-api/active_model_serializers/pull/1767) Replace raising/rescuing `CollectionSerializer::NoSerializerError`,
+  throw/catch `:no_serializer`. (@bf4)
+- [#1839](https://github.com/rails-api/active_model_serializers/pull/1839) `fields` tests demonstrating usage for both attributes and relationships. (@NullVoxPopuli)
+- [#1812](https://github.com/rails-api/active_model_serializers/pull/1812) add a code of conduct (@corainchicago)
+
+- [#1878](https://github.com/rails-api/active_model_serializers/pull/1878) Cache key generation for serializers now uses `ActiveSupport::Cache.expand_cache_key` instead of `Array#join` by default and is also overridable. This change should be backward-compatible. (@markiz)
+
+- [#1799](https://github.com/rails-api/active_model_serializers/pull/1799) Add documentation for setting the adapter. (@ScottKbka)
+- [#1909](https://github.com/rails-api/active_model_serializers/pull/1909) Add documentation for relationship links. (@vasilakisfil, @NullVoxPopuli)
+- [#1959](https://github.com/rails-api/active_model_serializers/pull/1959) Add documentation for root. (@shunsuke227ono)
+- [#1967](https://github.com/rails-api/active_model_serializers/pull/1967) Improve type method documentation. (@yukideluxe)
+
+### [v0.10.2 (2016-07-05)](https://github.com/rails-api/active_model_serializers/compare/v0.10.1...v0.10.2)
+
+Fixes:
+- [#1814](https://github.com/rails-api/active_model_serializers/pull/1814) Ensuring read_multi works with fragment cache
+- [#1848](https://github.com/rails-api/active_model_serializers/pull/1848) Redefine associations on inherited serializers. (@EhsanYousefi)
+
+Misc:
+- [#1808](https://github.com/rails-api/active_model_serializers/pull/1808) Adds documentation for `fields` option. (@luizkowalski)
+
+### [v0.10.1 (2016-06-16)](https://github.com/rails-api/active_model_serializers/compare/v0.10.0...v0.10.1)
+
+Features:
+- [#1668](https://github.com/rails-api/active_model_serializers/pull/1668) Exclude nil and empty links. (@sigmike)
+- [#1426](https://github.com/rails-api/active_model_serializers/pull/1426) Add ActiveModelSerializers.config.default_includes (@empact)
+
+Fixes:
+- [#1754](https://github.com/rails-api/active_model_serializers/pull/1754) Fixes #1759, Grape integration, improves serialization_context
+  missing error message on pagination. Document overriding CollectionSerializer#paginated?. (@bf4)
+  Moved serialization_context creation to Grape formatter, so resource serialization works without explicit calls to the `render` helper method.
+  Added Grape collection tests. (@onomated)
+- [#1287](https://github.com/rails-api/active_model_serializers/pull/1287) Pass `fields` options from adapter to serializer. (@vasilakisfil)
+- [#1710](https://github.com/rails-api/active_model_serializers/pull/1710) Prevent association loading when `include_data` option
+  is set to `false`. (@groyoh)
+- [#1747](https://github.com/rails-api/active_model_serializers/pull/1747) Improve jsonapi mime type registration for Rails 5 (@remear)
+
+Misc:
+- [#1734](https://github.com/rails-api/active_model_serializers/pull/1734) Adds documentation for conditional attribute (@lambda2)
+- [#1685](https://github.com/rails-api/active_model_serializers/pull/1685) Replace `IncludeTree` with `IncludeDirective` from the jsonapi gem.
+
+### [v0.10.0 (2016-05-17)](https://github.com/rails-api/active_model_serializers/compare/4a2d9853ba7...v0.10.0)
 
 Breaking changes:
 - [#1662](https://github.com/rails-api/active_model_serializers/pull/1662) Drop support for Rails 4.0 and Ruby 2.0.0. (@remear)
@@ -22,6 +100,7 @@ Fixes:
 
 Misc:
 - [#1673](https://github.com/rails-api/active_model_serializers/pull/1673) Adds "How to" guide on using AMS with POROs (@DrSayre)
+- [#1730](https://github.com/rails-api/active_model_serializers/pull/1730) Adds documentation for overriding default serializer based on conditions (@groyoh/@cgmckeever)
 
 ### [v0.10.0.rc5 (2016-04-04)](https://github.com/rails-api/active_model_serializers/compare/v0.10.0.rc4...v0.10.0.rc5)
 

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting one of the owners listed at https://rubygems.org/gems/active_model_serializers. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -38,16 +38,19 @@ gem 'tzinfo-data', platforms: (@windows_platforms + [:jruby])
 
 group :bench do
   # https://github.com/rails-api/active_model_serializers/commit/cb4459580a6f4f37f629bf3185a5224c8624ca76
-  gem 'benchmark-ips', require: false, group: :development
+  gem 'benchmark-ips', '>= 2.7.2', require: false, group: :development
 end
 
 group :test do
   gem 'sqlite3',                          platform: (@windows_platforms + [:ruby])
   gem 'activerecord-jdbcsqlite3-adapter', platform: :jruby
   gem 'codeclimate-test-reporter', require: false
+  gem 'm', '~> 1.5'
+  gem 'pry', '~> 0.10'
+  gem 'pry-byebug', '~> 3.4', platform: :ruby
 end
 
 group :development, :test do
-  gem 'rubocop', '~> 0.39.0', require: false
+  gem 'rubocop', '~> 0.40.0', require: false
   gem 'yard', require: false
 end

data/README.md

@@ -24,17 +24,6 @@
   </tr>
 </table>
 
-
-## Documentation
-
-- [0.10 (master) Documentation](https://github.com/rails-api/active_model_serializers/tree/master)
-  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/v0.10.0)
-  - [Guides](docs)
-- [0.9 (0-9-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-9-stable)
-  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/0-9-stable)
-- [0.8 (0-8-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-8-stable)
-  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/0-8-stable)
-
 ## About
 
 ActiveModelSerializers brings convention over configuration to your JSON generation.
@@ -50,33 +39,24 @@ resource serialization. The serialization has the `#as_json`, `#to_json` and `#s
 methods used by the Rails JSON Renderer. (SerializableResource actually delegates
 these methods to the adapter.)
 
-By default ActiveModelSerializers will use the **Attributes Adapter**.
+By default ActiveModelSerializers will use the **Attributes Adapter** (no JSON root).
 But we strongly advise you to use **JsonApi Adapter**, which
 follows 1.0 of the format specified in [jsonapi.org/format](http://jsonapi.org/format).
 Check how to change the adapter in the sections below.
 
-## RELEASE CANDIDATE, PLEASE READ
-
-This is the **master** branch of ActiveModelSerializers.
-
-It will become the `0.10.0` release when it's ready. Currently this is a release candidate.
-
 `0.10.x` is **not** backward compatible with `0.9.x` nor `0.8.x`.
 
-`0.10.x` will be based on the `0.8.0` code, but with a more flexible
+`0.10.x` is based on the `0.8.0` code, but with a more flexible
 architecture. We'd love your help. [Learn how you can help here.](CONTRIBUTING.md)
 
 It is generally safe and recommended to use the master branch.
 
-For more information, see the post '[The future of
-AMS](https://medium.com/@joaomdmoura/the-future-of-ams-e5f9047ca7e9)'.
-
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```
-gem 'active_model_serializers'
+gem 'active_model_serializers', '~> 0.10.0'
 ```
 
 And then execute:
@@ -103,8 +83,24 @@ If you'd like to chat, we have a [community slack](http://amserializers.herokuap
 
 Thanks!
 
+## Documentation
+- [0.10 (master) Documentation](https://github.com/rails-api/active_model_serializers/tree/master)
+  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/active_model_serializers/0.10.2)
+  - [Guides](docs)
+- [0.9 (0-9-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-9-stable)
+  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/0-9-stable)
+- [0.8 (0-8-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-8-stable)
+  - [![API Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/rails-api/active_model_serializers/0-8-stable)
+
+
 ## High-level behavior
 
+Choose an adapter from [adapters](lib/active_model_serializers/adapter):
+
+``` ruby
+ActiveModelSerializers.config.adapter = :json_api # Default: `:attributes`
+```
+
 Given a [serializable model](lib/active_model/serializer/lint.rb):
 
 ```ruby
@@ -162,6 +158,10 @@ serializer.associations
 ```
 See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for more information.
 
-# Contributing
+## Semantic Versioning
+
+This project adheres to [semver](http://semver.org/)
+
+## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)

data/Rakefile

@@ -5,7 +5,7 @@ rescue LoadError
 end
 begin
   require 'simplecov'
-rescue LoadError
+rescue LoadError # rubocop:disable Lint/HandleExceptions
 end
 
 Bundler::GemHelper.install_tasks
@@ -33,7 +33,7 @@ end
 begin
   require 'rubocop'
   require 'rubocop/rake_task'
-rescue LoadError
+rescue LoadError # rubocop:disable Lint/HandleExceptions
 else
   Rake::Task[:rubocop].clear if Rake::Task.task_defined?(:rubocop)
   require 'rbconfig'
@@ -100,4 +100,4 @@ else
 end
 
 desc 'CI test task'
-task :ci => [:default]
+task ci: [:default]

data/active_model_serializers.gemspec

@@ -19,33 +19,35 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
   spec.executables   = []
 
-  spec.required_ruby_version = '>= 2.0.0'
+  spec.required_ruby_version = '>= 2.1'
 
-  rails_versions = '>= 4.0'
+  rails_versions = ['>= 4.1', '< 6']
   spec.add_runtime_dependency 'activemodel', rails_versions
-    # 'activesupport', rails_versions
-    # 'builder'
+  # 'activesupport', rails_versions
+  # 'builder'
 
   spec.add_runtime_dependency 'actionpack', rails_versions
-    # 'activesupport', rails_versions
-    # 'rack'
-    # 'rack-test', '~> 0.6.2'
+  # 'activesupport', rails_versions
+  # 'rack'
+  # 'rack-test', '~> 0.6.2'
 
-  spec.add_runtime_dependency 'railties', rails_versions
-    # 'activesupport', rails_versions
-    # 'actionpack', rails_versions
-    # 'rake', '>= 0.8.7'
+  spec.add_development_dependency 'railties', rails_versions
+  # 'activesupport', rails_versions
+  # 'actionpack', rails_versions
+  # 'rake', '>= 0.8.7'
 
   # 'activesupport', rails_versions
-    # 'i18n,
-    # 'tzinfo'
-    # 'minitest'
-    # 'thread_safe'
+  # 'i18n,
+  # 'tzinfo'
+  # 'minitest'
+  # 'thread_safe'
+
+  spec.add_runtime_dependency 'jsonapi', '0.1.1.beta2'
 
   spec.add_development_dependency 'activerecord', rails_versions
-    # arel
-    # activesupport
-    # activemodel
+  # arel
+  # activesupport
+  # activemodel
 
   # Soft dependency for pagination
   spec.add_development_dependency 'kaminari', ' ~> 0.16.3'
@@ -57,10 +59,4 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'grape', ['>= 0.13', '< 1.0']
   spec.add_development_dependency 'json_schema'
   spec.add_development_dependency 'rake', ['>= 10.0', '< 12.0']
-
-  spec.post_install_message = <<-EOF
-NOTE: The default key case for the JsonApi adapter has changed to dashed.
-See https://github.com/rails-api/active_model_serializers/blob/master/docs/general/key_transforms.md
-for more information on configuring this behavior.
-EOF
 end

data/docs/ARCHITECTURE.md

@@ -15,7 +15,7 @@ It requires an adapter to transform its attributes into a JSON document; it cann
 It may be useful to think of it as a
 [presenter](http://blog.steveklabnik.com/posts/2011-09-09-better-ruby-presenters).
 
-The **`ActiveModel::ArraySerializer`** represent a collection of resources as serializers
+The **`ActiveModel::CollectionSerializer`** represents a collection of resources as serializers
 and, if there is no serializer, primitives.
 
 The **`ActiveModel::Adapter`** describes the structure of the JSON document generated from a
@@ -42,10 +42,9 @@ it is not modified.
 Internally, if no serializer can be found in the controller, the resource is not decorated by
 ActiveModelSerializers.
 
-If the collection serializer (ArraySerializer) cannot
-identify a serializer for a resource in its collection, it raises [`NoSerializerError`](https://github.com/rails-api/active_model_serializers/issues/1191#issuecomment-142327128)
-which is rescued in `ActiveModel::Serializer::Reflection#build_association` which sets
-the association value directly:
+If the collection serializer (CollectionSerializer) cannot
+identify a serializer for a resource in its collection, it throws [`:no_serializer`](https://github.com/rails-api/active_model_serializers/issues/1191#issuecomment-142327128).
+For example, when caught by `Reflection#build_association`, the association value is set directly:
 
 ```ruby
 reflection_options[:virtual_value] = association_value.try(:as_json) || association_value
@@ -85,8 +84,8 @@ Details:
   1. The serializer and adapter are created as
     1. `serializer_instance = serializer.new(resource, serializer_opts)`
     2. `adapter_instance = ActiveModel::Serializer::Adapter.create(serializer_instance, adapter_opts)`
-1. **ActiveModel::Serializer::ArraySerializer#new**
-  1. If the `serializer_instance` was a `ArraySerializer` and the `:serializer` serializer_opts
+1. **ActiveModel::Serializer::CollectionSerializer#new**
+  1. If the `serializer_instance` was a `CollectionSerializer` and the `:serializer` serializer_opts
     is present, then [that serializer is passed into each resource](https://github.com/rails-api/active_model_serializers/blob/a54d237e2828fe6bab1ea5dfe6360d4ecc8214cd/lib/active_model/serializer/array_serializer.rb#L14-L16).
 1. **ActiveModel::Serializer#attributes** is used by the adapter to get the attributes for
   resource as defined by the serializer.

data/docs/README.md

@@ -24,10 +24,12 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 
 - [How to add root key](howto/add_root_key.md)
 - [How to add pagination links](howto/add_pagination_links.md)
+- [How to add relationship links](howto/add_relationship_links.md)
 - [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md)
 - [Testing ActiveModelSerializers](howto/test.md)
 - [Passing Arbitrary Options](howto/passing_arbitrary_options.md)
 - [How to serialize a Plain-Old Ruby Object (PORO)](howto/serialize_poro.md)
+- [How to upgrade from `0.8` to `0.10` safely](howto/upgrade_from_0_8_to_0_10.md)
 
 ## Integrations
 

data/docs/general/adapters.md

@@ -67,9 +67,11 @@ Doesn't follow any specific convention.
 
 ### JSON
 
-The response document always with a root key.
+The json response is always rendered with a root key.
 
-The root key **can't be overridden**, and will be derived from the resource being serialized.
+The root key can be overridden by:
+* passing the `root` option in the render call. See details in the [Rendering Guides](rendering.md#overriding-the-root-key).
+* setting the `type` of the serializer. See details in the [Serializers Guide](serializers.md#type).
 
 Doesn't follow any specific convention.
 

data/docs/general/caching.md

@@ -2,6 +2,12 @@
 
 # Caching
 
+## Warning
+
+There is currently a problem with caching in AMS [Caching doesn't improve performance](https://github.com/rails-api/active_model_serializers/issues/1586). Adding caching _may_ slow down your application, rather than speeding it up. We suggest you benchmark any caching you implement before using in a production enviroment
+
+___
+
 To cache a serializer, call ```cache``` and pass its options.
 The options are the same options of ```ActiveSupport::Cache::Store```, plus
 a ```key``` option that will be the prefix of the object cache
@@ -17,7 +23,7 @@ The cache support is optimized to use the cached object in multiple request. An
 cache(options = nil) # options: ```{key, expires_in, compress, force, race_condition_ttl}```
 ```
 
-Take the example bellow:
+Take the example below:
 
 ```ruby
 class PostSerializer < ActiveModel::Serializer

data/docs/general/configuration_options.md

@@ -46,15 +46,71 @@ Each adapter has a default key transform configured:
 
 | Adapter | Default Key Transform |
 |----|----|
+| `Attributes` | `:unaltered` |
 | `Json` | `:unaltered` |
 | `JsonApi` | `:dash` |
 
 `config.key_transform` is a global override of the adapter default. Adapters
 still prefer the render option `:key_transform` over this setting.
 
+*NOTE: Key transforms can be expensive operations. If key transforms are unnecessary for the
+application, setting `config.key_transform` to `:unaltered` will provide a performance boost.*
 
-## JSON API
+##### default_includes
+What relationships to serialize by default.  Default: `'*'`, which includes one level of related
+objects. See [includes](adapters.md#included) for more info.
+
+
+##### serializer_lookup_chain
+
+Configures how serializers are searched for. By default, the lookup chain is
+
+```ruby
+ActiveModelSerializers::LookupChain::DEFAULT
+```
+
+which is shorthand for
+
+```ruby
+[
+  ActiveModelSerializers::LookupChain::BY_PARENT_SERIALIZER,
+  ActiveModelSerializers::LookupChain::BY_NAMESPACE,
+  ActiveModelSerializers::LookupChain::BY_RESOURCE_NAMESPACE,
+  ActiveModelSerializers::LookupChain::BY_RESOURCE
+]
+```
+
+Each of the array entries represent a proc. A serializer lookup proc will be yielded 3 arguments. `resource_class`, `serializer_class`, and `namespace`.
+
+Note that:
+ - `resource_class` is the class of the resource being rendered
+ - by default `serializer_class` is `ActiveModel::Serializer`
+   - for association lookup it's the "parent" serializer
+ - `namespace` correspond to either the controller namespace or the [optionally] specified [namespace render option](./rendering.md#namespace)
+
+An example config could be:
+
+```ruby
+ActiveModelSerializers.config.serializer_lookup_chain = [
+  lambda do |resource_class, serializer_class, namespace|
+    "API::#{namespace}::#{resource_class}"
+  end
+]
+```
 
+If you simply want to add to the existing lookup_chain. Use `unshift`.
+
+```ruby
+ActiveModelSerializers.config.serializer_lookup_chain.unshift(
+  lambda do |resource_class, serializer_class, namespace|
+    # ...
+  end
+)
+```
+
+See [lookup_chain.rb](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/lookup_chain.rb) for further explanations and examples.
+
+## JSON API
 
 ##### jsonapi_resource_type
 
@@ -67,6 +123,19 @@ Possible values:
 - `:singular`
 - `:plural` (default)
 
+##### jsonapi_namespace_separator
+
+Sets separator string for namespaced models to render `type` attribute.
+
+
+| Separator | Example: Admin::User |
+|----|----|
+| `'-'` (default) | 'admin-users'
+| `'--'` (recommended) | 'admin--users'
+
+See [Recommendation for dasherizing (kebab-case-ing) namespaced object, such as `Admin::User`](https://github.com/json-api/json-api/issues/850)
+for more discussion.
+
 ##### jsonapi_include_toplevel_object
 
 Include a [top level jsonapi member](http://jsonapi.org/format/#document-jsonapi-object)

data/docs/general/deserialization.md

@@ -42,7 +42,7 @@ document = {
       'title' => 'Title 1',
       'date' => '2015-12-20'
     },
-    'associations' => {
+    'relationships' => {
       'author' => {
         'data' => {
           'type' => 'user',

data/docs/general/fields.md

@@ -0,0 +1,31 @@
+[Back to Guides](../README.md)
+
+# Fields
+
+If for any reason, you need to restrict the fields returned, you should use `fields` option.
+
+For example, if you have a serializer like this
+
+```ruby
+class UserSerializer < ActiveModel::Serializer
+  attributes :access_token, :first_name, :last_name
+end
+```
+
+and in a specific controller, you want to return `access_token` only, `fields` will help you:
+
+```ruby
+class AnonymousController < ApplicationController
+  def create
+    render json: User.create(activation_state: 'anonymous'), fields: [:access_token], status: 201
+  end
+end
+```
+
+Note that this is only valid for the `json` and `attributes` adapter. For the `json_api` adapter, you would use
+
+```ruby
+render json: @user, fields: { users: [:access_token] }
+```
+
+Where `users` is the JSONAPI type.