active_model_serializers 0.10.0.rc3 → 0.10.0.rc4

data/CONTRIBUTING.md

@@ -1,31 +1,220 @@
+First of all, **thank you**!
+
+![Commit Strip
+http://www.commitstrip.com/en/2014/05/07/the-truth-behind-open-source-apps/](docs/how-open-source-maintained.jpg)
+
+## Common issues and resolutions
+
+- Using `grape-active_model_serializers`, or any non-Rails server. See
+    [issue](https://github.com/rails-api/active_model_serializers/issues/1258).
+
 ## How can I help?
 
-Everyone is encouraged to open issues that are affecting you: bugs, ideas, performance problems – everything helps!
+- [Filing an issue](CONTRIBUTING.md#filing-an-issue)
+- [Writing code and comments](CONTRIBUTING.md#writing-code-and-comments)
+
+### Filing an issue
+
+Everyone is encouraged to open issues that are affecting them:
+bugs, ideas, documentation (`/docs`), performance problems – everything helps!
+
+#### Before
+
+1. Start by looking at our [GitHub Issues](https://github.com/rails-api/active_model_serializers/issues).
+
+  - Check if your issue has already been reported.
+  - If you find an existing issue report, feel free to add further information to that report.
+
+#### Writing
+
+If possible, please include the following information when [reporting an
+issue](https://github.com/rails-api/active_model_serializers/issues/new):
+
+- ActiveModelSerializers version (0.8.x, 0.9.x, 0.10.x, commit ref).
+- What are you using ActiveModelSerializers with? Rails? Grape? Other? Which versions?
+- If you are not running the latest version (please check), and you cannot update it,
+  please specify in your report why you can't update to the latest version.
+- Operating system type + version.
+- Ruby version with patch level.  And whether you're using rvm, rbenv, etc.
+  - Include `ruby -e "puts RUBY_DESCRIPTION"`.
+- Clearly-written steps to reproduce the issue (i.e. "Show me how to show myself." ), including:
+  - What were you doing? Include code if possible.
+    - Command line parameters used, if any.
+    - RubyGems code in your Gemfile, if any. Gemfile.lock, if possible.
+    - Any configuration you've made.
+  - What did you expect to happen?
+  - What happened? Include as much information as possible.
+    - Nature of reported defect (e.g. user name missing, not "It doesn't work."). Is it intermittent?
+    - The best help here is a failing test. Even better if it's a PR.
+    - Then the steps to reproduce and/or a gist or repository that demonstrates the defect.
+    - Then examples of the code you were using.
+    - Any error messages (including stacktrace, i.e. "Show me the error.")
+  - Things you've tried.
+  - A pull request for your fix would be great.  Code should have tests.
+  - Link to source code, if available.
+
+Please make sure only to include one issue per report.
+If you encounter multiple, unrelated issues, please report them as such.
+
+Simon Tatham has written an excellent on article on
+[How to Report Bugs Effectively](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html)
+which is [well worth reading](http://yourbugreportneedsmore.info/), although it is not specific to ActiveModelSerializers.
+
+Include as much sample code as you can to help us reproduce the issue. (Inline, repo link, or gist, are fine. A failing test would help the most.)
+
+This is extremely important for narrowing down the cause of your problem.
+
+Thanks!
+
+Sometimes an issue will be closed by a maintainer for various reasons.  In some cases, this is
+an invitation to make a better case for your issue or be able to reproduce a bug, and
+its being close is just an opportunity to help out some more, and then re-open.
+
+#### After
+
+Thanks to everyone involved!
+
+If you get help, sharing it back in the form of a pull-request or making an issue to document
+what you've found is *extremely* helpful.
+
+If you solve your issue, stop working on it, or realize the problem was something else,
+please share that in a comment to an issue and close it.  That way, everyone can learn and
+we don't have closed issues without a clear resolution. Even if it's just a stackoverflow link :)
+And please don't forget to stay involved in the issue until it is closed! Thanks to all!
+
+### Writing code and comments
 
-The first place to start is by looking at our [GitHub Issues](https://github.com/rails-api/active_model_serializers/issues).
+- We are actively working to identify tasks under the label [**Good for New
+  Contributors**](https://github.com/rails-api/active_model_serializers/labels/Good%20for%20New%20Contributors).
+  - [Changelog
+      Missing](https://github.com/rails-api/active_model_serializers/issues?q=label%3A%22Changelog+Missing%22+is%3Aclosed) is
+    an easy way to help out.
 
-The vast majority of development is happening under the `master` branch, currently slated for release as `0.10.x`. This is where we would suggest you start.
+- [Fix a bug](https://github.com/rails-api/active_model_serializers/labels/Ready%20for%20PR).
+  - Ready for PR - A well defined bug, needs someone to PR a fix.
+  - Bug - Anything that is broken.
+  - Regression - A bug that did not exist in previous versions and isn't a new feature (applied in tandem with Bug).
+  - Performance - A performance related issue. We could track this as a bug, but usually these would have slightly lower priority than standard bugs.
 
-Fixing bugs is extraordinarily helpful and requires the least familiarity with AMS. Look for issues labeled [**Needs Bug Verification**](https://github.com/rails-api/active_model_serializers/labels/Needs%20Bug%20Verification) and [**Bug**](https://github.com/rails-api/active_model_serializers/labels/bug).
+- [Develop new features](https://github.com/rails-api/active_model_serializers/labels/Feature).
 
-We are also actively working to identify tasks under the label [**Good for New Contributors**](https://github.com/rails-api/active_model_serializers/labels/Good%20for%20New%20Contributors). Some bugs are expressly not good for new contributors, so don't expect 100% overlap between the two.
+- [Improve code quality](https://codeclimate.com/github/rails-api/active_model_serializers/code?sort=smell_count&sort_direction=desc).
 
-If you want to work on new feature development, look for the label [**Feature**](https://github.com/rails-api/active_model_serializers/labels/Feature).
+- [Improve amount of code exercised by tests](https://codeclimate.com/github/rails-api/active_model_serializers/coverage?sort=covered_percent&sort_direction=asc).
 
-We are also encouraging comments to substantial changes (larger than bugfixes and simple features) under an "RFC" (Request for Comments) process before we start active development. Look for the [**RFC**](https://github.com/rails-api/active_model_serializers/labels/RFC) label.
+- [Fix RuboCop (Style) TODOS](https://github.com/rails-api/active_model_serializers/blob/master/.rubocop_todo.yml).
+  - Delete and offsense, run `rake rubocop` (or possibly `rake rubocop:auto_correct`),
+    and [submit a PR](CONTRIBUTING.md#submitting-a-pull-request-pr).
+
+- We are also encouraging comments to substantial changes (larger than bugfixes and simple features) under an
+  "RFC" (Request for Comments) process before we start active development.
+   Look for the [**RFC**](https://github.com/rails-api/active_model_serializers/labels/RFC) label.
+
+#### Submitting a pull request (PR)
+
+1. The vast majority of development is happening under the `master` branch.
+  This is where we would suggest you start.
+1. Fixing bugs is extraordinarily helpful and requires the least familiarity with ActiveModelSerializers.
+  Look for issues labeled [**Needs Bug Verification**](https://github.com/rails-api/active_model_serializers/labels/Needs%20Bug%20Verification) and [**Bug**](https://github.com/rails-api/active_model_serializers/labels/bug).
+1. Adding or fixing documentation is also fantastic!
+
+To fetch & test the library for development, do:
+
+1. Fork the repository ( https://github.com/rails-api/active_model_serializers/fork )
+1. `git clone https://github.com/{whoami}/active_model_serializers.git`
+1. `cd active_model_serializers`
+1. `bundle`
+  - To test against a particular rails version-- 4.0 is usually the most buggy-- set then
+      RAILS_VERSION environment variable as described in the [.travis.yml](.travis.yml).
+      e.g. `export RAILS_VERSION=4.0`.
+1. Create your PR branch (`git checkout -b my-helpful-pr`)
+1. Write tests for your feature, or regression tests highlighting a bug.
+  This is important so ActiveModelSerializers doesn't break it in a future version unintentionally.
+1. Write the feature itself, or fix your bug
+1. `bundle exec rake`
+1. Commit your changes (`git commit -am 'Add some feature'`)
+  - Use well-described, small (atomic) commits.
+1. Push to the branch (`git push origin my-helpful-pr`)
+1. Create a new Pull Request
+  - Include links to any relevant github issues.
+  - *Don't* change the VERSION file.
+  - Update `/docs` to include, whenever possible, a new, suitable recommendation about how to use
+    the feature.
+  - Extra Credit: [Confirm it runs and tests pass on the rubies specified in the travis
+    config](.travis.yml). A maintainer will otherwise confirm it runs on these.
+
+1. *Bonus Points* Update [CHANGELOG.md](https://github.com/rails-api/active_model_serializers/blob/master/CHANGELOG.md)
+  with a brief description of any breaking changes, fixes, features, or
+  miscellaneous changes under the proper version section.
+1. Iterate on feedback given by the community (fix syntax, modify bits of code, add
+tests), pushing the new commits to the PR each time
+
+Remember to [squash your commits](CONTRIBUTING.md#about-pull-requests-prs) and rebase off `master`.
+
+#### How maintainers handle pull requests:
+
+- If the tests pass and the pull request looks good, a maintainer will merge it.
+- If the pull request needs to be changed,
+  - you can change it by updating the branch you generated the pull request from
+    - either by adding more commits, or
+    - by force pushing to it
+  - A maintainer can make any changes themselves and manually merge the code in.
+
+#### Commit Messages
+
+- [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
+- [http://stopwritingramblingcommitmessages.com/](http://stopwritingramblingcommitmessages.com/)
+- [ThoughtBot style guide](https://github.com/thoughtbot/guides/tree/master/style#git)
+
+#### About Pull Requests (PR's)
+
+- [Using Pull Requests](https://help.github.com/articles/using-pull-requests)
+- [Github pull requests made easy](http://www.element84.com/github-pull-requests-made-easy.html)
+- [Exercism Git Workflow](http://help.exercism.io/git-workflow.html).
+- [Level up your Git](http://rakeroutes.com/blog/deliberate-git/)
+- [All Your Open Source Code Are Belong To Us](http://www.benjaminfleischer.com/2013/07/30/all-your-open-source-code-are-belong-to-us/)
 
 ## Issue Labeling
 
-AMS uses a subset of [StandardIssueLabels](https://github.com/wagenet/StandardIssueLabels) for Github Issues. You can [see our labels here](https://github.com/rails-api/active_model_serializers/labels).
+ActiveModelSerializers uses a subset of [StandardIssueLabels](https://github.com/wagenet/StandardIssueLabels) for Github Issues. You can [see our labels here](https://github.com/rails-api/active_model_serializers/labels).
+
+## Running tests
+
+Run tests against different Rails versions by setting the RAILS_VERSION variable
+and bundling gems.  To test against all versions, you can do something like:
+
+```bash
+for version in 4.0 4.1 4.2 master; do
+  export RAILS_VERSION="$version"
+  rm -f Gemfile.lock
+  bundle check || bundle --local || bundle
+  bundle exec rake test
+  if [ "$?" -eq 0 ]; then
+    # green in ANSI
+    echo -e "\033[32m **** Tests passed against Rails ${RAILS_VERSION} **** \033[0m"
+  else
+    # red in ANSI
+    echo -e "\033[31m **** Tests failed against Rails ${RAILS_VERSION} **** \033[0m"
+  fi
+  unset RAILS_VERSION
+done
+```
+
+
+### Running with Rake
+
+The easiest way to run the unit tests is through Rake. The default task runs
+the entire test suite for all classes. For more information, checkout the
+full array of rake tasks with "rake -T"
+
+Rake can be found at http://docs.seattlerb.org/rake/.
+
+To run a single test suite
+
+`$ rake test TEST=path/to/test.rb`
 
-## Contributing
+Which can be further narrowed down to one test:
 
-1. Fork it ( https://github.com/rails-api/active_model_serializers/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Write tests for your feature, or regression tests highlighting a bug
-4. Write the feature itself, or fix your bug
-5. Commit your changes (`git commit -am 'Add some feature'`)
-6. Push to the branch (`git push origin my-new-feature`)
-7. Create a new Pull Request
+`$ rake test TEST=path/to/test.rb TESTOPTS="--name=test_something"`
 
-Remember to squash your commits and rebase off `master`.
+:heart: :sparkling_heart: :heart:

data/Gemfile

@@ -11,38 +11,39 @@ version = ENV['RAILS_VERSION'] || '4.2'
 
 if version == 'master'
   gem 'rack', github: 'rack/rack'
+  gem 'arel', github: 'rails/arel'
   git 'https://github.com/rails/rails.git' do
     gem 'railties'
     gem 'activesupport'
     gem 'activemodel'
     gem 'actionpack'
+    gem 'activerecord', group: :test
     # Rails 5
     gem 'actionview'
   end
-  # Rails 5
-  gem 'rails-controller-testing', github: 'rails/rails-controller-testing'
 else
   gem_version = "~> #{version}.0"
   gem 'railties', gem_version
   gem 'activesupport', gem_version
   gem 'activemodel', gem_version
   gem 'actionpack', gem_version
+  gem 'activerecord', gem_version, group: :test
 end
 
+# https://github.com/bundler/bundler/blob/89a8778c19269561926cea172acdcda241d26d23/lib/bundler/dependency.rb#L30-L54
+@windows_platforms = [:mswin, :mingw, :x64_mingw]
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem 'tzinfo-data', platforms: (@windows_platforms + [:jruby])
+
 group :test do
-  gem 'activerecord'
-  gem 'sqlite3', platform: [:ruby, :mingw, :x64_mingw, :mswin]
+  gem 'sqlite3',                          platform: (@windows_platforms + [:ruby])
   gem 'activerecord-jdbcsqlite3-adapter', platform: :jruby
-  gem 'codeclimate-test-reporter', require: false
-end
 
-group :test, :development do
-  gem 'simplecov', '~> 0.10', require: false
+  gem 'codeclimate-test-reporter', require: false
+  gem 'simplecov', '~> 0.10', require: false, group: :development
 end
 
-# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
-gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
-
 group :development, :test do
   gem 'rubocop', '~> 0.34.0', require: false
 end

data/README.md

@@ -1,216 +1,53 @@
-# ActiveModel::Serializer
+# ActiveModelSerializers
 
-[![Build Status](https://travis-ci.org/rails-api/active_model_serializers.svg)](https://travis-ci.org/rails-api/active_model_serializers)
-<a href="https://codeclimate.com/github/rails-api/active_model_serializers"><img src="https://codeclimate.com/github/rails-api/active_model_serializers/badges/gpa.svg" /></a>
-<a href="https://codeclimate.com/github/rails-api/active_model_serializers/coverage"><img src="https://codeclimate.com/github/rails-api/active_model_serializers/badges/coverage.svg" /></a>
+[![Build Status](https://travis-ci.org/rails-api/active_model_serializers.svg?branch=master)](https://travis-ci.org/rails-api/active_model_serializers)
+(Windows: [![Build status](https://ci.appveyor.com/api/projects/status/x6xdjydutm54gvyt/branch/master?svg=true)](https://ci.appveyor.com/project/joaomdmoura/active-model-serializers/branch/master))
+[![Code Quality](https://codeclimate.com/github/rails-api/active_model_serializers/badges/gpa.svg)](https://codeclimate.com/github/rails-api/active_model_serializers)
+[![Test Coverage](https://codeclimate.com/github/rails-api/active_model_serializers/badges/coverage.svg)](https://codeclimate.com/github/rails-api/active_model_serializers/coverage)
 
-_Windows Build Status -_ [![Build status](https://ci.appveyor.com/api/projects/status/x6xdjydutm54gvyt/branch/master?svg=true)](https://ci.appveyor.com/project/joaomdmoura/active-model-serializers/branch/master)
+## Documentation
 
-ActiveModel::Serializer brings convention over configuration to your JSON generation.
+- [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)
+  - [Guides](docs)
+- [0.9 (0-9-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-9-stable)
+- [0.8 (0-8-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-8-stable)
 
-AMS does this through two components: **serializers** and **adapters**.
-Serializers describe _which_ attributes and relationships should be serialized.
-Adapters describe _how_ attributes and relationships should be serialized.
-
-By default AMS will use the **Flatten Json Adapter**. But we strongly advise you to use **JsonApi Adapter** that follows 1.0 of the format specified in [jsonapi.org/format](http://jsonapi.org/format).
-Check how to change the adapter in the sections bellow.
-
-# RELEASE CANDIDATE, PLEASE READ
-
-This is the master branch of AMS. It will become the `0.10.0` release when it's
-ready. Currently this is a release candidate. This is **not** backward
-compatible with `0.9.0` or `0.8.0`.
-
-`0.10.x` will be based on the `0.8.0` code, but with a more flexible
-architecture. We'd love your help. [Learn how you can help here.](https://github.com/rails-api/active_model_serializers/blob/master/CONTRIBUTING.md)
-
-## Example
-
-Given two models, a `Post(title: string, body: text)` and a
-`Comment(name: string, body: text, post_id: integer)`, you will have two
-serializers:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  cache key: 'posts', expires_in: 3.hours
-  attributes :title, :body
-
-  has_many :comments
-end
-```
-
-and
-
-```ruby
-class CommentSerializer < ActiveModel::Serializer
-  attributes :name, :body
-
-  belongs_to :post
-end
-```
-
-Generally speaking, you as a user of AMS will write (or generate) these
-serializer classes. If you want to use a different adapter, such as a JsonApi, you can
-change this in an initializer:
-
-```ruby
-ActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::JsonApi
-```
-
-or
-
-```ruby
-ActiveModel::Serializer.config.adapter = :json_api
-```
-
-You won't need to implement an adapter unless you wish to use a new format or
-media type with AMS.
-
-If you want to have a root key on your responses you should use the Json adapter, instead of the default FlattenJson:
-
-```ruby
-ActiveModel::Serializer.config.adapter = :json
-```
-
-If you would like the key in the outputted JSON to be different from its name in ActiveRecord, you can use the :key option to customize it:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :body
-
-  # look up :subject on the model, but use +title+ in the JSON
-  attribute :subject, :key => :title
-  has_many :comments
-end
-```
-
-In your controllers, when you use `render :json`, Rails will now first search
-for a serializer for the object and use it if available.
-
-```ruby
-class PostsController < ApplicationController
-  def show
-    @post = Post.find(params[:id])
-
-    render json: @post
-  end
-end
-```
-
-In this case, Rails will look for a serializer named `PostSerializer`, and if
-it exists, use it to serialize the `Post`.
-
-### Specify a serializer
-
-If you wish to use a serializer other than the default, you can explicitly pass it to the renderer.
-
-#### 1. For a resource:
-
-```ruby
-  render json: @post, serializer: PostPreviewSerializer
-```
-
-#### 2. For an array resource:
-
-```ruby
-# Use the default `ArraySerializer`, which will use `each_serializer` to
-# serialize each element
-render json: @posts, each_serializer: PostPreviewSerializer
-
-# Or, you can explicitly provide the collection serializer as well
-render json: @posts, serializer: CollectionSerializer, each_serializer: PostPreviewSerializer
-```
-
-### Meta
-
-If you want a `meta` attribute in your response, specify it in the `render`
-call:
-
-```ruby
-render json: @post, meta: { total: 10 }
-```
-
-The key can be customized using `meta_key` option.
-
-```ruby
-render json: @post, meta: { total: 10 }, meta_key: "custom_meta"
-```
-
-`meta` will only be included in your response if you are using an Adapter that supports `root`, as JsonAPI and Json adapters, the default adapter (FlattenJson) doesn't have `root`.
-
-### Using a serializer without `render`
+## About
 
-At times, you might want to use a serializer without rendering it to the view. For those cases, you can create an instance of `ActiveModel::SerializableResource` with
-the resource you want to be serialized and call `.serializable_hash`.
-
-```ruby
-def create
-  @message = current_user.messages.create!(message_params)
-  MessageCreationWorker.perform(serialized_message)
-  head 204
-end
-
-def serialized_message
-  ActiveModel::SerializableResource.new(@message).serializable_hash
-end
-```
-
-### Overriding association methods
-
-If you want to override any association, you can use:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :body
-
-  has_many :comments
-
-  def comments
-    object.comments.active
-  end
-end
-```
+ActiveModelSerializers brings convention over configuration to your JSON generation.
 
-### Overriding attribute methods
+ActiveModelSerializers works through two components: **serializers** and **adapters**.
 
-If you want to override any attribute, you can use:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :body
+Serializers describe _which_ attributes and relationships should be serialized.
 
-  has_many :comments
+Adapters describe _how_ attributes and relationships should be serialized.
 
-  def body
-    object.body.downcase
-  end
-end
-```
+SerializableResource co-ordinates the resource, Adapter and Serializer to produce the
+resource serialization. The serialization has the `#as_json`, `#to_json` and `#serializable_hash`
+methods used by the Rails JSON Renderer. (SerializableResource actually delegates
+these methods to the adapter.)
 
-### Built in Adapters
+By default ActiveModelSerializers will use the **Attributes Adapter**.
+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.
 
-#### FlattenJSON
+## RELEASE CANDIDATE, PLEASE READ
 
-It's the default adapter, it generates a json response without a root key.
-Doesn't follow any specifc convention.
+This is the **master** branch of ActiveModelSerializers.
 
-#### JSON
+It will become the `0.10.0` release when it's ready. Currently this is a release candidate.
 
-It also generates a json response but always with a root key. The root key **can't be overridden**, and will be automatically defined accordingly with the objects being serialized.
-Doesn't follow any specifc convention.
+`0.10.x` is **not** backward compatible with `0.9.x` nor `0.8.x`.
 
-#### JSONAPI
+`0.10.x` will be 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)
 
-This adapter follows 1.0 of the format specified in
-[jsonapi.org/format](http://jsonapi.org/format). It will include the associated
-resources in the `"included"` member when the resource names are included in the
-`include` option. Including nested associated resources is also supported.
+It is generally safe and recommended to use the master branch.
 
-```ruby
-  render @posts, include: ['author', 'comments', 'comments.author']
-  # or
-  render @posts, include: 'author,comments,comments.author'
-```
+For more information, see the post '[The future of
+AMS](https://medium.com/@joaomdmoura/the-future-of-ams-e5f9047ca7e9)'.
 
 ## Installation
 
@@ -226,128 +63,83 @@ And then execute:
 $ bundle
 ```
 
-## Creating a Serializer
+## Getting Started
 
-The easiest way to create a new serializer is to generate a new resource, which
-will generate a serializer at the same time:
+See [Getting Started](docs/general/getting_started.md) for the nuts and bolts.
 
-```
-$ rails g resource post title:string body:string
-```
+More information is available in the [Guides](docs) and
+[High-level behavior](README.md#high-level-behavior).
 
-This will generate a serializer in `app/serializers/post_serializer.rb` for
-your new model. You can also generate a serializer for an existing model with
-the serializer generator:
+## Getting Help
 
-```
-$ rails g serializer post
-```
+If you find a bug, please report an [Issue](https://github.com/rails-api/active_model_serializers/issues/new)
+and see our [contributing guide](CONTRIBUTING.md).
 
-The generated seralizer will contain basic `attributes` and
-`has_many`/`has_one`/`belongs_to` declarations, based on the model. For example:
+If you have a question, please [post to Stack Overflow](http://stackoverflow.com/questions/tagged/active-model-serializers).
 
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :title, :body
+If you'd like to chat, we have a [community slack](http://amserializers.herokuapp.com).
 
-  has_many :comments
-  has_one :author
-end
-```
+Thanks!
 
-and
+## High-level behavior
 
-```ruby
-class CommentSerializer < ActiveModel::Serializer
-  attributes :name, :body
+Given a [serializable model](lib/active_model/serializer/lint.rb):
 
-  belongs_to :post_id
+```ruby
+# either
+class SomeResource < ActiveRecord::Base
+  # columns: title, body
+end
+# or
+class SomeResource < ActiveModelSerializers::Model
+  attr_accessor :title, :body
 end
 ```
 
-The attribute names are a **whitelist** of attributes to be serialized.
-
-The `has_many`, `has_one`, and `belongs_to` declarations describe relationships between
-resources. By default, when you serialize a `Post`, you will get its `Comments`
-as well.
-
-You may also use the `:serializer` option to specify a custom serializer class, for example:
+And initialized as:
 
 ```ruby
-  has_many :comments, serializer: CommentPreviewSerializer
+resource = SomeResource.new(title: 'ActiveModelSerializers', body: 'Convention over configuration')
 ```
 
-And you can change the JSON key that the serializer should use for a particular association:
+Given a serializer for the serializable model:
 
 ```ruby
-  has_many :comments, key: :reviews
+class SomeSerializer < ActiveModel::Serializer
+  attribute :title, key: :name
+  attributes :body
+end
 ```
 
-## Pagination
-
-Pagination links will be included in your response automatically as long as the resource is paginated using [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate) and if you are using a ```JSON-API``` adapter.
-
-Although the others adapters does not have this feature, it is possible to implement pagination links to `JSON` adapter. For more information about it, please see in our docs [How to add pagination links](https://github.com/rails-api/active_model_serializers/blob/master/docs/howto/add_pagination_links.md)
-
-## Caching
-
-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
-on a pattern ```"#{key}/#{object.id}-#{object.updated_at}"```.
-
-The cache support is optimized to use the cached object in multiple request. An object cached on a ```show``` request will be reused at the ```index```. If there is a relationship with another cached serializer it will also be created and reused automatically.
-
-**[NOTE] Every object is individually cached.**
-
-**[NOTE] The cache is automatically expired after an object is updated, but it's not deleted.**
+The model can be serialized as:
 
 ```ruby
-cache(options = nil) # options: ```{key, expires_in, compress, force, race_condition_ttl}```
+options = {}
+serialization = SerializableResource.new(resource, options)
+serialization.to_json
+serialization.as_json
 ```
 
-Take the example bellow:
+SerializableResource delegates to the adapter, which it builds as:
 
 ```ruby
-class PostSerializer < ActiveModel::Serializer
-  cache key: 'post', expires_in: 3.hours
-  attributes :title, :body
-
-  has_many :comments
-end
+adapter_options = {}
+adapter = Adapter.create(serializer, adapter_options)
+adapter.to_json
+adapter.as_json
+adapter.serializable_hash
 ```
 
-On this example every ```Post``` object will be cached with
-the key ```"post/#{post.id}-#{post.updated_at}"```. You can use this key to expire it as you want,
-but in this case it will be automatically expired after 3 hours.
-
-### Fragmenting Caching
-
-If there is some API endpoint that shouldn't be fully cached, you can still optimise it, using Fragment Cache on the attributes and relationships that you want to cache.
-
-You can define the attribute by using ```only``` or ```except``` option on cache method.
-
-**[NOTE] Cache serializers will be used at their relationships**
-
-Example:
+The adapter formats the serializer's attributes and associations (a.k.a. includes):
 
 ```ruby
-class PostSerializer < ActiveModel::Serializer
-  cache key: 'post', expires_in: 3.hours, only: [:title]
-  attributes :title, :body
-
-  has_many :comments
-end
+serializer_options = {}
+serializer = SomeSerializer.new(resource, serializer_options)
+serializer.attributes
+serializer.associations
 ```
-
-## Getting Help
-
-If you find a bug, please report an [Issue](https://github.com/rails-api/active_model_serializers/issues/new).
-
-If you have a question, please [post to Stack Overflow](http://stackoverflow.com/questions/tagged/active-model-serializers).
-
-Thanks!
+See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for more information.
 
 # Contributing
 
-See [CONTRIBUTING.md](https://github.com/rails-api/active_model_serializers/blob/master/CONTRIBUTING.md)
+See [CONTRIBUTING.md](CONTRIBUTING.md)