Added documentation for upgrading.
This commit is contained in:
dblock
parent
7a5c304454
commit
76ae2fd111
|
|
@ -1,9 +1,11 @@
|
|||
## Next
|
||||
## 2.2 (Next)
|
||||
|
||||
**Note:** This version introduces several backward incompatible API changes. See [UPGRADING](UPGRADING.md) for details.
|
||||
|
||||
* [#146](https://github.com/intridea/hashie/issues/146): Mash#respond_to? inconsistent with #method_missing and does not respond to #permitted? - [@dblock](https://github.com/dblock).
|
||||
* [#89](https://github.com/intridea/hashie/issues/89): Added Hashie::Extensions::Mash::ActiveModel for compatibility with Rails 4.x Strong Parameters - [@dblock](https://github.com/dblock).
|
||||
* [#152](https://github.com/intridea/hashie/pull/152): Do not convert keys to String in Hashie::Dash and Hashie::Trash - [@dblock](https://github.com/dblock).
|
||||
* [#152](https://github.com/intridea/hashie/pull/152): Do not automatically stringify keys in Hashie::Hash#to_hash, pass `:stringify_keys` - [@dblock](https://github.com/dblock).
|
||||
* [#152](https://github.com/intridea/hashie/pull/152): Do not convert keys to String in Hashie::Dash and Hashie::Trash, use Hashie::Extensions::Dash::IndifferentAccess to achieve backward compatible behavior - [@dblock](https://github.com/dblock).
|
||||
* [#152](https://github.com/intridea/hashie/pull/152): Do not automatically stringify keys in Hashie::Hash#to_hash, pass `:stringify_keys` to achieve backward compatible behavior - [@dblock](https://github.com/dblock).
|
||||
* [#148](https://github.com/intridea/hashie/pull/148): Consolidated Hashie::Hash#stringify_keys implementation - [@dblock](https://github.com/dblock).
|
||||
* Your contribution here.
|
||||
|
||||
|
|
|
|||
10
README.md
10
README.md
|
|
@ -10,6 +10,10 @@ Hashie is available as a RubyGem:
|
|||
$ gem install hashie
|
||||
```
|
||||
|
||||
## Upgrading
|
||||
|
||||
You're reading the documentation for the next release of Hashie, which should be 2.2. Please read [UPGRADING](UPGRADING.md) when upgrading from a previous version. The current stable release is [2.1.1](https://github.com/intridea/hashie/blob/v2.1.1/README.md).
|
||||
|
||||
## Hash Extensions
|
||||
|
||||
The library is broken up into a number of atomically includeable Hash extension modules as described below. This provides maximum flexibility for users to mix and match functionality while maintaining feature parity with earlier versions of Hashie.
|
||||
|
|
@ -77,6 +81,8 @@ This extension can be mixed in to instantly give you indifferent access to your
|
|||
|
||||
A unique feature of Hashie's IndifferentAccess mixin is that it will inject itself recursively into subhashes *without* reinitializing the hash in question. This means you can safely merge together indifferent and non-indifferent hashes arbitrarily deeply without worrying about whether you'll be able to `hash[:other][:another]` properly.
|
||||
|
||||
Use `Hashie::Extensions::Dash::IndifferentAccess` for instances of `Hashie::Dash`.
|
||||
|
||||
### IgnoreUndeclared
|
||||
|
||||
This extension can be mixed in to silently ignore undeclared properties on initialization instead of raising an error. This is useful when using a Trash to capture a subset of a larger hash.
|
||||
|
|
@ -230,7 +236,9 @@ p.trick # => NoMethodError
|
|||
|
||||
### Mash and Rails 4 Strong Parameters
|
||||
|
||||
Add the following initializer in config/initializers/mash.rb when using Mash with [Rails 4 Strong Parameters](http://edgeguides.rubyonrails.org/action_controller_overview.html#strong-parameters). This prevents Mash from responding to `:permitted?` and therefore triggering an ActiveModel `ForbiddenAttributesProtection` exception.
|
||||
If you're using [Rails 4 strong parameters](http://edgeguides.rubyonrails.org/action_controller_overview.html#strong-parameters), you will get a [ForbiddenAttributesProtection](https://github.com/rails/strong_parameters/blob/master/lib/active_model/forbidden_attributes_protection.rb) exceptions when mass-assigning attributes.
|
||||
|
||||
To allow mass assignment, add the following initializer in config/initializers/mash.rb. This prevents Mash from responding to `:permitted?` and therefore triggering this behavior in [ForbiddenAttributesProtection](https://github.com/rails/strong_parameters/blob/master/lib/active_model/forbidden_attributes_protection.rb).
|
||||
|
||||
```ruby
|
||||
class Mash
|
||||
|
|
|
|||
|
|
@ -0,0 +1,95 @@
|
|||
Upgrading Hashie
|
||||
================
|
||||
|
||||
### Upgrading to 2.2
|
||||
|
||||
#### Compatibility with Rails 4 Strong Parameters
|
||||
|
||||
Version 2.1 introduced support to prevent default Rails 4 mass-assignment protection behavior. This was [issue #89](https://github.com/intridea/hashie/issues/89), resolved in [#104](https://github.com/intridea/hashie/pull/104). In version 2.2 this behavior has been removed in [#147](https://github.com/intridea/hashie/pull/147) in favor of a mixin.
|
||||
|
||||
To enable 2.1 compatible behavior, add the following initializer in config/initializers/mash.rb. This prevents Mash from responding to `:permitted?` and therefore triggering this behavior in [ForbiddenAttributesProtection](https://github.com/rails/strong_parameters/blob/master/lib/active_model/forbidden_attributes_protection.rb).
|
||||
|
||||
```ruby
|
||||
class Mash
|
||||
include Hashie::Extensions::Mash::ActiveModel
|
||||
end
|
||||
```
|
||||
|
||||
See [Mash and Rails 4 Strong Parameters](README.md#mash-and-rails-4-strong-parameters) for more details.
|
||||
|
||||
#### Key Conversions in Hashie::Dash and Hashie::Trash
|
||||
|
||||
Version 2.1 and older of Hashie::Dash and Hashie::Trash converted keys to strings by default. This is no longer the case in 2.2.
|
||||
|
||||
Consider the following code.
|
||||
|
||||
```ruby
|
||||
class Person < Hashie::Dash
|
||||
property :name
|
||||
end
|
||||
|
||||
p = Person.new(name: 'dB.')
|
||||
```
|
||||
|
||||
Version 2.1 behaves as follows.
|
||||
|
||||
```ruby
|
||||
p.name # => 'dB.'
|
||||
p[:name] # => 'dB.'
|
||||
p['name'] # => 'dB.'
|
||||
|
||||
# not what I put in
|
||||
p.inspect # => { 'name' => 'dB.' }
|
||||
p.to_hash # => { 'name' => 'dB.' }
|
||||
```
|
||||
|
||||
It was not possible to achieve the behavior of preserving keys, as described in [issue #151](https://github.com/intridea/hashie/issues/151).
|
||||
|
||||
Version 2.2 does not perform this conversion by default.
|
||||
|
||||
```ruby
|
||||
p.name # => 'dB.'
|
||||
p[:name] # => 'dB.'
|
||||
# p['name'] # => NoMethodError
|
||||
|
||||
p.inspect # => { :name => 'dB.' }
|
||||
p.to_hash # => { :name => 'dB.' }
|
||||
```
|
||||
|
||||
To enable behavior compatible with older versions, use `Hashie::Extensions::Dash::IndifferentAccess`.
|
||||
|
||||
```ruby
|
||||
class Person < Hashie::Dash
|
||||
include Hashie::Extensions::Dash::IndifferentAccess
|
||||
property :name
|
||||
end
|
||||
```
|
||||
|
||||
#### Key Conversions in Hashie::Hash#to_hash
|
||||
|
||||
Version 2.1 or older of Hash#to_hash converted keys to strings automatically.
|
||||
|
||||
```ruby
|
||||
instance = Hashie::Hash[first: 'First', 'last' => 'Last']
|
||||
instance.to_hash # => { "first" => 'First', "last" => 'Last' }
|
||||
```
|
||||
|
||||
It was possible to symbolize keys by passing `:symbolize_keys`, however it was not possible to retrieve the hash with initial key values.
|
||||
|
||||
```ruby
|
||||
instance.to_hash(symbolize_keys: true) # => { :first => 'First', :last => 'Last' }
|
||||
instance.to_hash(stringify_keys: true) # => { "first" => 'First', "last" => 'Last' }
|
||||
```
|
||||
|
||||
Version 2.2 no longer converts keys by default.
|
||||
|
||||
```ruby
|
||||
instance = Hashie::Hash[first: 'First', 'last' => 'Last']
|
||||
instance.to_hash # => { :first => 'First', "last" => 'Last' }
|
||||
```
|
||||
|
||||
The behavior with `symbolize_keys` and `stringify_keys` is unchanged.
|
||||
|
||||
See [#152](https://github.com/intridea/hashie/pull/152) for more information.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue