Organize the 4.0 release notes

Distinguishing changes, additions, and fixes helps users to upgrade.

[ci skip]

CHANGELOG.md

@@ -1,5 +1,10 @@
 ## 4.0.0 (Unreleased)
 
+This major release adds JSON column support in PostgreSQL, limited support for
+versioning associations, various new configuration options, and a year's worth
+of bug fixes. Thanks to everyone who helped test the two betas and two release
+candidates.
+
 ### Changed
 
 - Using a Rails initializer to reopen PaperTrail::Version or otherwise extend
@@ -8,11 +13,25 @@
   https://github.com/airblade/paper_trail/pull/492.
 - If you depend on the `RSpec` or `Cucumber` helpers, you must
   [require them in your test helper](https://github.com/airblade/paper_trail#testing).
+- [#458](https://github.com/airblade/paper_trail/pull/458) - Version metadata
+  (the `:meta` option) from AR attributes for `create` events will now save the
+  current value instead of `nil`.
+- [#391](https://github.com/airblade/paper_trail/issues/391) - `object_changes`
+  value should dump to `YAML` as a normal `Hash` instead of an
+  `ActiveSupport::HashWithIndifferentAccess`.
+- [#375](https://github.com/airblade/paper_trail/pull/375) /
+  [#374](https://github.com/airblade/paper_trail/issues/374) /
+  [#354](https://github.com/airblade/paper_trail/issues/354) /
+  [#131](https://github.com/airblade/paper_trail/issues/131) -
+  Versions are now saved with an `after_` callback, instead of a `before_`
+  callback. This ensures that the timestamp field for a version matches the
+  corresponding timestamp in the model.
+- `3da1f104` - `PaperTrail.config` and `PaperTrail.configure` are now
+  identical: both return the `PaperTrail::Config` instance and also
+  yield it if a block is provided.
 
 ### Added
 
-  - [#541](https://github.com/airblade/paper_trail/pull/541) -
-    `PaperTrail.config.enabled` should be Thread Safe
 - [#525](https://github.com/airblade/paper_trail/issues/525) /
   [#512](https://github.com/airblade/paper_trail/pull/512) -
   Support for virtual accessors and redefined setter and getter methods.
@@ -21,32 +40,49 @@
   [`JSON` and `JSONB` column types](http://www.postgresql.org/docs/9.4/static/datatype-json.html)
   via `PaperTrail::VersionConcern#where_object` and
   `PaperTrail::VersionConcern#where_object_changes`
-  - [#507](https://github.com/airblade/paper_trail/pull/507) - Support for
+- [#507](https://github.com/airblade/paper_trail/pull/507) -
-    opting out of saving changesets on models by choice when the
+  New option: `:save_changes` controls whether or not to save changes to the
-    `object_changes` column exists on the default `versions` table.
+  `object_changes` column (if it exists).
 - [#500](https://github.com/airblade/paper_trail/pull/500) - Support for
-    passing `on: []` as an argument, with only manual versioning via calls to
+  passing an empty array to the `on` option (`on: []`) to disable all
-    `touch_with_version`
+  automatic versioning.
 - [#494](https://github.com/airblade/paper_trail/issues/494) - The install
   generator will warn the user if the migration they are attempting to
   generate already exists.
 - [#484](https://github.com/airblade/paper_trail/pull/484) - Support for
   [PostgreSQL's `JSONB` Type](http://www.postgresql.org/docs/9.4/static/datatype-json.html)
   for storing `object` and `object_changes`.
-  - [#479](https://github.com/airblade/paper_trail/issues/479) - Deprecated
+- [#439](https://github.com/airblade/paper_trail/pull/439) /
-    `originator` method, use `paper_trail_originator`.
+  [#12](https://github.com/airblade/paper_trail/issues/12) -
-  - [#458](https://github.com/airblade/paper_trail/pull/458) - For `create`
+  Support for versioning associations (has many, has one, etc.) one level deep.
-    events, metadata pointing at attributes should attempt to grab the current
+- [#420](https://github.com/airblade/paper_trail/issues/420) - Add
-    value instead of looking at the value prior to the change (which would
+  `VersionConcern#where_object_changes` instance method; acts as a helper for
-    always be `nil`)
+  querying against the `object_changes` column in versions table.
+- [#416](https://github.com/airblade/paper_trail/issues/416) - Added a
+  `config` option for enabling/disabling utilization of
+  `serialized_attributes` for `ActiveRecord`, necessary because
+  `serialized_attributes` has been deprecated in `ActiveRecord` version `4.2`
+  and will be removed in version `5.0`
+- [#399](https://github.com/airblade/paper_trail/pull/399) - Add `:dup`
+  argument for options hash to `reify` which forces a new model instance.
+- [#394](https://github.com/airblade/paper_trail/pull/394) - Add RSpec matcher
+  `have_a_version_with` for easier testing.
+- [#347](https://github.com/airblade/paper_trail/pull/347) - Autoload
+  `ActiveRecord` models in via a `Rails::Engine` when the gem is used with
+  `Rails`.
+
+### Fixed
+
+- [#563](https://github.com/airblade/paper_trail/pull/563) - Fixed a bug in
+  `touch_with_version` so that it will still create a version even when the
+  `on` option is, e.g. `[:create]`.
+- [#541](https://github.com/airblade/paper_trail/pull/541) -
+  `PaperTrail.config.enabled` should be Thread Safe
 - [#451](https://github.com/airblade/paper_trail/issues/451) - Fix `reify`
   method in context of model where the base class has a default scope, and the
   live instance is not scoped within that default scope.
 - [#440](https://github.com/airblade/paper_trail/pull/440) - `versions`
   association should clear/reload after a transaction rollback.
-  - [#439](https://github.com/airblade/paper_trail/pull/439) /
-    [#12](https://github.com/airblade/paper_trail/issues/12) -
-    Support for versioning of associations (Has Many, Has One, HABTM, etc.)
 - [#438](https://github.com/airblade/paper_trail/issues/438) -
   `ModelKlass.paper_trail_enabled_for_model?` should return `false` if
   `has_paper_trail` has not been declared on the class.
@@ -59,53 +95,25 @@
   `ActiveRecord` 4.1.x
 - [#427](https://github.com/airblade/paper_trail/pull/427) - Fix `reify`
   method in context of model where a column has been removed.
-  - [#420](https://github.com/airblade/paper_trail/issues/420) - Add
-    `VersionConcern#where_object_changes` instance method; acts as a helper for
-    querying against the `object_changes` column in versions table.
-  - [#416](https://github.com/airblade/paper_trail/issues/416) - Added a
-    `config` option for enabling/disabling utilization of
-    `serialized_attributes` for `ActiveRecord`, necessary because
-    `serialized_attributes` has been deprecated in `ActiveRecord` version `4.2`
-    and will be removed in version `5.0`
 - [#414](https://github.com/airblade/paper_trail/issues/414) - Fix
   functionality `ignore` argument to `has_paper_trail` in `ActiveRecord` 4.
 - [#413](https://github.com/airblade/paper_trail/issues/413) - Utilize
   [RequestStore](https://github.com/steveklabnik/request_store) to ensure that
   the `PaperTrail.whodunnit` is set in a thread safe manner within Rails and
   Sinatra.
-  - [#399](https://github.com/airblade/paper_trail/pull/399) - Add `:dup`
+- [#381](https://github.com/airblade/paper_trail/issues/381) - Fix `irb`
-    argument for options hash to `reify` which forces a new model instance.
+  warning: `can't alias context from irb_context`. `Rspec` and `Cucumber`
-  - [#394](https://github.com/airblade/paper_trail/pull/394) - Add RSpec matcher
+  helpers should not be loaded by default, regardless of whether those
-    `have_a_version_with` for easier testing.
+  libraries are loaded.
-  - [#391](https://github.com/airblade/paper_trail/issues/391) - `object_changes`
-    value should dump to `YAML` as a normal `Hash` instead of an
-    `ActiveSupport::HashWithIndifferentAccess`.
-  - [#381](https://github.com/airblade/paper_trail/issues/381) - `Rspec`
-    and `Cucumber` helpers should not be loaded by default, regardless of
-    whether those libraries are loaded.
-  - [#375](https://github.com/airblade/paper_trail/pull/375) /
-    [#374](https://github.com/airblade/paper_trail/issues/374) /
-    [#354](https://github.com/airblade/paper_trail/issues/354) /
-    [#131](https://github.com/airblade/paper_trail/issues/131) -
-    Versions should be built with `after_` callbacks so the timestamp field for
-    a version can be forced to match the corresponding timestamp in the database
-    for the state persistence of a change to the base (versioned) model.
-  - [#347](https://github.com/airblade/paper_trail/pull/347) - Autoload
-    `ActiveRecord` models in via a `Rails::Engine` when the gem is used with
-    `Rails`.
-  - Methods handling serialized attributes should fallback to the currently set
-    Serializer instead of always falling back to `PaperTrail::Serializers::YAML`.
-  - Both `PaperTrail.config` and `PaperTrail.configure` are now identical, and
-    will both return the `PaperTrail::Config` instance and also yield it if a
-    block is provided.
-
-### Fixed
-
-  - [#563](https://github.com/airblade/paper_trail/pull/563) - Fixed a bug in
-    `touch_with_version` so that it will still create a version even when the
-    `on` option is, e.g. `[:create]`.
 - [#248](https://github.com/airblade/paper_trail/issues/248) - In MySQL, to
   prevent truncation, generated migrations now use `longtext` instead of `text`.
+- Methods handling serialized attributes should fallback to the currently set
+  Serializer instead of always falling back to `PaperTrail::Serializers::YAML`.
+
+### Deprecated
+
+- [#479](https://github.com/airblade/paper_trail/issues/479) - Deprecated
+  `originator` method, use `paper_trail_originator`.
 
 ## 3.0.8