From 9a56be4d468e45d1ca2f09d168d5b467cc91cf9a Mon Sep 17 00:00:00 2001
From: dblock <dblock@dblock.org>
Date: Tue, 17 May 2016 12:13:06 -0400
Subject: [PATCH] Added CHANGELOG, CONTRIBUTING, updated README and UPGRADING.
 [ci skip]

---
 CHANGELOG.md    |  36 ++++++++++++++
 CONTRIBUTING.md | 126 ++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       | 108 +++++++++++------------------------------
 UPGRADING.md    | 100 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 291 insertions(+), 79 deletions(-)
 create mode 100644 CHANGELOG.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 UPGRADING.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..1bfee39
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,36 @@
+## Changelog
+
+### 1.4.0 (Next)
+
+* [#49](https://github.com/jrhe/grape-active_model_serializers/pull/49): Adds support for active model serializer namespace - [@syntaxTerr0r](https://github.com/syntaxTerr0r).
+* [#36](https://github.com/jrhe/grape-active_model_serializers/pull/36), [#50](https://github.com/jrhe/grape-active_model_serializers/pull/50): Added support through Grape 0.16.x - [@dblock](https://github.com/dblock).
+
+### v1.3.2 (February 27, 2015)
+
+* [#39](https://github.com/jrhe/grape-active_model_serializers/pull/39): Look for namespace and other options to configure serializers - [@jwkoelewijn](https://github.com/jwkoelewijn).
+* [#40](https://github.com/jrhe/grape-active_model_serializers/pull/40): Use env to pass AMS meta around - [@dblock](https://github.com/dblock).
+
+### v1.3.1 (November 20, 2014)
+
+* [#30](https://github.com/jrhe/grape-active_model_serializers/pull/30): Read options from default_serializer_options - [@siong1987](https://github.com/siong1987).
+* [#24](https://github.com/jrhe/grape-active_model_serializers/pull/24): Makes it possible to use `current_user` within serializers - [@sonxurxo](https://github.com/sonxurxo).
+
+### v1.2.1 (July 23, 2014)
+
+* [#21](https://github.com/jrhe/grape-active_model_serializers/pull/21): Correctly fetch serialization scope - [@radanskoric](https://github.com/radanskoric).
+* [#18](https://github.com/jrhe/grape-active_model_serializers/pull/18): Added support for active model serializer 0.9.x - [@sbounmy](https://github.com/sbounmy).
+
+* [#15](https://github.com/jrhe/grape-active_model_serializers/pull/15): Added `render` syntactic sugar - [@zph](https://github.com/zph).
+* [#14](https://github.com/jrhe/grape-active_model_serializers/pull/14): Fix: `default_root` method to support symbol route in Grape - [@wjp2013](https://github.com/wjp2013).
+* [#12](https://github.com/jrhe/grape-active_model_serializers/pull/12): Added support for `current_user` - [@kpassapk](https://github.com/kpassapk).
+* [#11](https://github.com/jrhe/grape-active_model_serializers/pull/11): Fixed require path - [@schickling](https://github.com/schickling).
+
+### v1.0.1 (September 9, 2013)
+
+* [#6](https://github.com/jrhe/grape-active_model_serializers/pull/6): Conform to ActiveModel::Serializers way of determining array-ness - [@tfe](https://github.com/tfe).
+* [#4](https://github.com/jrhe/grape-active_model_serializers/pull/4): Support for namespace options and rely more on active_model_serializers - [@johnallen3d](https://github.com/johnallen3d).
+* [#1](https://github.com/jrhe/grape-active_model_serializers/pull/1): Fix: Grape::ActiveModelSerializers for models with compound names - [@george](https://github.com/george).
+
+### v1.0.0
+
+* Initial public release - [@jrhe](https://github.com/jrhe).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..9ce2718
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,126 @@
+# Contributing to Grape-Swagger
+
+This project is work of [many contributors](https://github.com/jrhe/grape-active_model_serializers/graphs/contributors).
+You're encouraged to submit [pull requests](https://github.com/jrhe/grape-active_model_serializers/pulls),
+[propose features and discuss issues](https://github.com/jrhe/grape-active_model_serializers/issues).
+When in doubt, ask a question in the [Grape Google Group](http://groups.google.com/group/ruby-grape).
+
+In the examples below, substitute your Github username for `contributor` in URLs.
+
+## Fork the Project
+
+Fork the [project on Github](https://github.com/jrhe/grape-active_model_serializers) and check out your copy.
+
+```
+git clone https://github.com/contributor/grape-active_model_serializers.git
+cd grape-active_model_serializers
+git remote add upstream https://github.com/jrhe/grape-active_model_serializers.git
+```
+
+## Create a Topic Branch
+
+Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.
+
+```
+git checkout master
+git pull upstream master
+git checkout -b my-feature-branch
+```
+
+## Bundle Install and Test
+
+Ensure that you can build the project and run tests.
+
+```
+bundle install
+bundle exec rake
+```
+
+## Write Tests
+
+Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build.
+Add to [spec](spec).
+
+We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
+
+## Write Code
+
+Implement your feature or bug fix.
+
+Ruby style is enforced with [RuboCop](https://github.com/bbatsov/rubocop).
+Run `bundle exec rubocop` and fix any style issues highlighted.
+
+Make sure that `bundle exec rake` completes without errors.
+
+## Write Documentation
+
+Document any external behavior in the [README](README.md).
+
+## Update Changelog
+
+Add a line to [CHANGELOG](CHANGELOG.md) under *Next Release*.
+Make it look like every other line, including your name and link to your Github account.
+
+## Commit Changes
+
+Make sure git knows your name and email address:
+
+```
+git config --global user.name "Your Name"
+git config --global user.email "contributor@example.com"
+```
+
+Writing good commit logs is important. A commit log should describe what changed and why.
+
+```
+git add ...
+git commit
+```
+
+## Push
+
+```
+git push origin my-feature-branch
+```
+
+## Make a Pull Request
+
+Go to https://github.com/contributor/grape-active_model_serializers and select your feature branch.
+Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.
+
+## Rebase
+
+If you've been working on a change for a while, rebase with upstream/master.
+
+```
+git fetch upstream
+git rebase upstream/master
+git push origin my-feature-branch -f
+```
+
+## Update CHANGELOG Again
+
+Update the [CHANGELOG](CHANGELOG.md) with the pull request number. A typical entry looks as follows.
+
+```
+* [#123](https://github.com/jrhe/grape-active_model_serializers/pull/123): Reticulated splines - [@contributor](https://github.com/contributor).
+```
+
+Amend your previous commit and force push the changes.
+
+```
+git commit --amend
+git push origin my-feature-branch -f
+```
+
+## Check on Your Pull Request
+
+Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI. Everything should look green, otherwise fix issues and amend your commit as described above.
+
+## Be Patient
+
+It's likely that your change will not be merged and that the nitpicky maintainers will ask you to do more, or fix seemingly benign problems. Hang on there!
+
+## Thank You
+
+Please do know that we really appreciate and value your time and work. We love you, really.
diff --git a/README.md b/README.md
index 3c977b9..cc56d79 100644
--- a/README.md
+++ b/README.md
@@ -2,26 +2,17 @@
 
 Use [active_model_serializers](https://github.com/rails-api/active_model_serializers) with [Grape](https://github.com/intridea/grape)!
 
-[![Build Status](https://api.travis-ci.org/jrhe/grape-active_model_serializers.png)](http://travis-ci.org/jrhe/grape-active_model_serializers) [![Dependency Status](https://gemnasium.com/jrhe/grape-active_model_serializers.png)](https://gemnasium.com/jrhe/grape-active_model_serializers) [![Code Climate](https://codeclimate.com/github/jrhe/grape-active_model_serializers.png)](https://codeclimate.com/github/jrhe/grape-active_model_serializers)
-
-## Breaking Changes
-#### v1.4.0
-* *BREAKING* Changes behaviour in serializer namespacing when using Grape API versioning. See [API versioning](https://github.com/jrhe/grape-active_model_serializers#api-versioning)
-#### v1.0.0
-* *BREAKING* Changes behaviour of root keys when serialising arrays. See [Array roots](https://github.com/jrhe/grape-active_model_serializers#array-roots)
+[![Build Status](https://api.travis-ci.org/jrhe/grape-active_model_serializers.svg)](http://travis-ci.org/jrhe/grape-active_model_serializers) [![Dependency Status](https://gemnasium.com/jrhe/grape-active_model_serializers.svg)](https://gemnasium.com/jrhe/grape-active_model_serializers) [![Code Climate](https://codeclimate.com/github/jrhe/grape-active_model_serializers.svg)](https://codeclimate.com/github/jrhe/grape-active_model_serializers)
 
 ## Installation
 
-Add the `grape` and `grape-active_model_serializers` gems to Gemfile.
+Add the `grape` and `grape-active_model_serializers` gems to Gemfile and run `bundle install`.
 
 ```ruby
-gem 'grape'
 gem 'grape-active_model_serializers'
 ```
 
-And then execute:
-
-    bundle
+See [UPGRADING](UPGRADING.md) if you're upgrading from a previous version.
 
 ## Usage
 
@@ -32,7 +23,6 @@ And then execute:
 require 'grape-active_model_serializers'
 ```
 
-
 ### Tell your API to use Grape::Formatter::ActiveModelSerializers
 
 ```ruby
@@ -42,8 +32,7 @@ class API < Grape::API
 end
 ```
 
-
-### Writing serializers
+### Writing Serializers
 
 See [active_model_serializers](https://github.com/rails-api/active_model_serializers)
 
@@ -61,8 +50,11 @@ end
 ```
 In this case, as User objects are being returned, grape-active_model_serializers will look for a serializer named UserSerializer.
 
-### 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 (e.g. get 'name').
+### 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.
+
+In the following API the array root is `users`.
 
 ```ruby
 namespace :users do
@@ -70,51 +62,45 @@ namespace :users do
     @user = User.find(params[:id])
   end
 end
-# root = users
 ```
 
+In the following example the array root is `people`.
+
 ```ruby
 get "people" do
   @user = User.all
 end
-# root = people
 ```
 
-### API versioning
+### API Versioning
 
-If you haven't declared an API version in Grape, nothing change.
+If your Grape API is versioned you must namespace your serializers accordingly.
 
-If your Grape API is versioned, which means you have declared at least one version in Grape, ie:
+For example, given the following API.
 
 ```ruby
 module CandyBar
   class Core < Grape::API
     version 'candy_bar', using: :header, vendor: 'acme'
-
-    # My shiny endpoints
-    # ...
   end
 end
 
 module Chocolate
   class Core < Grape::API
     version 'chocolate', using: :header, vendor: 'acme'
-
-    # My shiny endpoints
-    # ...    
   end
 end
 
-class API < Grape::API  
+class API < Grape::API
   format :json
   formatter :json, Grape::Formatter::ActiveModelSerializers
 
   mount CandyBar::Core
-  mount Chocolate::Core  
+  mount Chocolate::Core
 end
 ```
 
-You'll have to namespace your serializers according to each version, ie:
+Namespace your serializers according to each version.
 
 ```ruby
 module CandyBar
@@ -130,7 +116,7 @@ module Chocolate
 end
 ```
 
-Which allow you to keep your serializers easier to maintain and more organized.
+This keeps serializers organized.
 
 ```
 app
@@ -147,7 +133,7 @@ app
         └── user_serializer.rb
 ```
 
-or alternatively:
+Or as follows.
 
 ```
 └── serializers
@@ -155,7 +141,7 @@ or alternatively:
     └── candy_bar_user_serializer.rb
 ```
 
-Thus, ActiveModelSerializer will fetch automatically the right serializer to render.
+ActiveModelSerializer will fetch automatically the right serializer to render.
 
 ### Manually specifying serializer options
 
@@ -178,7 +164,7 @@ namespace 'foo', serializer: BarSerializer do
 end
 ```
 
-### Custom metadata along with the resources
+### Custom Metadata
 
 ```ruby
 # Control any additional metadata using meta and meta_key
@@ -188,23 +174,21 @@ get "/homes"
 end
 ```
 
-### Support for `default_serializer_options`
+### Default Serializer Options
 
 ```ruby
 helpers do
   def default_serializer_options
-    {only: params[:only], except: params[:except]}
+    { only: params[:only], except: params[:except] }
   end
 end
 ```
 
-### current_user
+### Current User
 
-One of the nice features of ActiveModel::Serializers is that it
-provides access to the authorization context via the `current_user`.
+One of the nice features of ActiveModel::Serializers is that it provides access to the authorization context via the `current_user`.
 
-In Grape, you can get the same behavior by defining a `current_user`
-helper method:
+In Grape, you can get the same behavior by defining a `current_user` helper method.
 
 ```ruby
 helpers do
@@ -218,12 +202,10 @@ helpers do
 end
 ```
 
-Then, in your serializer, you could show or hide some elements
-based on the current user's permissions:
+Then, in your serializer, you could show or hide some elements based on the current user's permissions.
 
 ```ruby
 class PostSerializer < ActiveModel::Serializer
-...
   def include_admin_comments?
     current_user.roles.member? :admin
   end
@@ -252,42 +234,10 @@ end
 API.new.get "/home" # => '{ user: { first_name: "JR", last_name: "HE" } }'
 ```
 
-
-## RSpec
-
-See "Writing Tests" in https://github.com/intridea/grape.
-
-Enjoy :)
-
-## Changelog
-
-#### Next
-* Adds support for Grape 0.10.x
-
-#### v1.4.0
-* Adds support for active model serializer namespace
-
-#### v1.2.1
-* Adds support for active model serializer 0.9.x
-
-
-#### v1.0.0
-* Released on rubygems.org
-* *BREAKING* Changes behaviour of root keys when serialising arrays. See [Array roots](https://github.com/jrhe/grape-active_model_serializers#array-roots)
-
-
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+See [CONTRIBUTING](CONTRIBUTING.md).
 
-
-## Thanks to
-The developers and maintainers of:
-[active_model_serializers](https://github.com/rails-api/active_model_serializers)
-[Grape](https://github.com/intridea/grape)!
+## History
 
 Structured and based upon [grape-rabl](https://github.com/LTe/grape-rabl).
diff --git a/UPGRADING.md b/UPGRADING.md
new file mode 100644
index 0000000..a007aa1
--- /dev/null
+++ b/UPGRADING.md
@@ -0,0 +1,100 @@
+### Upgrading to v.1.4.0
+
+#### Changes in Serializer Namespacing
+
+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.
+
+For example, given the following API.
+
+```ruby
+module CandyBar
+  class Core < Grape::API
+    version 'candy_bar', using: :header, vendor: 'acme'
+  end
+end
+
+module Chocolate
+  class Core < Grape::API
+    version 'chocolate', using: :header, vendor: 'acme'
+  end
+end
+
+class API < Grape::API
+  format :json
+  formatter :json, Grape::Formatter::ActiveModelSerializers
+
+  mount CandyBar::Core
+  mount Chocolate::Core
+end
+```
+
+Namespace serializers according to each version.
+
+```ruby
+module CandyBar
+  class UserSerializer < ActiveModel::Serializer
+    attributes :first_name, :last_name, :email
+  end
+end
+
+module Chocolate
+  class UserSerializer < ActiveModel::Serializer
+    attributes :first_name, :last_name
+  end
+end
+```
+
+This will allow you to keep your serializers easier to maintain and more organized.
+
+```
+app
+└── api
+    ├── chocolate
+        └── core.rb
+    └── candy_bar
+        └── core.rb
+    api.rb
+└── serializers
+    ├── chocolate
+        └── user_serializer.rb
+    └── candy_bar
+        └── user_serializer.rb
+```
+
+or alternatively:
+
+```
+└── serializers
+    ├── chocolate_user_serializer.rb
+    └── candy_bar_user_serializer.rb
+```
+
+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.
+
+In the following example the array root is `users`.
+
+```ruby
+namespace :users do
+  get ":id" do
+    @user = User.find(params[:id])
+  end
+end
+```
+
+In the following example the array root is `people`.
+
+```ruby
+get "people" do
+  @user = User.all
+end
+```