acts_as_paranoid 0.6.1 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06cfbf17cb1f8fe737c00e223cc6b02f8ea1159d751c3e6c1bfba1fd077ca6ac
-  data.tar.gz: b887b92760729053b6286412ee861e9677c7d418bcf28bdfdc996c4e9474ed30
+  metadata.gz: 73cbdef60cb81f9506a3763c13b0380f83169b8c68f0b914305d828b90202d25
+  data.tar.gz: 2023f4db3125ff3db3dd9dc7b0fb0142e92d6f8f54bc433557d5dd0dc40fb853
 SHA512:
-  metadata.gz: 699e32ad650195f1d4b34ef89e266a379ef35f450d6434d753227788fe214c3af9ebe410397799117b8b6527a240d769e768cc1a60b49f8abd663d8e1ab81ff9
-  data.tar.gz: a5e7745201cfe1fb5689726ca93cff4fb24a594373a10c2fb7777541f9ca7dcb2681a20ddd91692eff6dae3149b80e6a962b56dc4fecd86d10b87e77f9be1221
+  metadata.gz: 1c7b2ff7d8655621915c11630012ff946a196b46fd0a175facad75d90aa4f6ecae1ae6df1e627f9cf778faa46d26fb559b275e62101a4ba402007d545014f43d
+  data.tar.gz: ec47e5232127609e3e83b9bf22b142a821e955b55a77e082f21ceaeb5e62c390253fee6815cfc3a4a795257eb68c15f29eb5adbad8e511703718e4278d84e52c

data/CHANGELOG.md

@@ -2,15 +2,77 @@
 
 Notable changes to this project will be documented in this file.
 
+## 0.7.2
+
+* Do not set boolean column to NULL on recovery if nulls are not allowed
+  ([#193], by [Shodai Suzuki][soartec-lab])
+* Add a CONTRIBUTING.md file ([#207], by [Matijs van Zuijlen][mvz])
+
+## 0.7.1
+
+* Support Rails 6.1 ([#191], by [Matijs van Zuijlen][mvz])
+* Support `belongs_to` with both `:touch` and `:counter_cache` options ([#208],
+  by [Matijs van Zuijlen][mvz] with [Paul Druziak][pauldruziak])
+* Support Ruby 3.0 ([#209], by [Matijs van Zuijlen][mvz])
+
+## 0.7.0
+
+### Breaking changes
+
+* Support Rails 5.2+ only ([#126], by [Daniel Rice][danielricecodes])
+* Update set of supported rubies to 2.4-2.7 ([#144], [#173] by [Matijs van Zuijlen][mvz])
+
+### Improvements
+
+* Handle `with_deleted` association option as a scope ([#147], by [Matijs van Zuijlen][mvz])
+* Simplify validation override ([#158], by [Matijs van Zuijlen][mvz])
+* Use correct unscope syntax so unscope works on Rails Edge ([#160],
+  by [Matijs van Zuijlen][mvz])
+* Fix ruby 2.7 keyword argument deprecation warning ([#161], by [Jon Riddle][wtfspm])
+
+### Documentation
+
+* Document save after destroy behavior ([#146], by [Matijs van Zuijlen][mvz])
+* Update version number instructions for installing gem ([#164],
+  by [Kevin McAlear][kevinmcalear])
+* Add example with `destroyed_fully?` and `deleted_fully?` to the readme ([#170],
+  by [Kiril Mitov][thebravoman])
+
+### Internal
+
+* Improve code quality using RuboCop ([#148], [#152], [#159], [#163], [#171] and [#173],
+  by [Matijs van Zuijlen][mvz])
+* Measure code coverage using SimpleCov ([#150] and [#175] by [Matijs van Zuijlen][mvz])
+* Silence warnings emitted during tests ([#156], by [Matijs van Zuijlen][mvz])
+* Make rake tasks more robust and intuitive ([#157], by [Matijs van Zuijlen][mvz])
+
+## 0.6.3
+
+* Update Travis CI configuration ([#137], by [Matijs van Zuijlen][mvz])
+* Add predicate to check if record was soft deleted or hard deleted ([#136],
+  by [Aymeric Le Dorze][aymeric-ledorze])
+* Add support for recover! method ([#75], by [vinoth][avinoth])
+* Fix a record being dirty after destroying it ([#135], by
+  [Aymeric Le Dorze][aymeric-ledorze])
+
+## 0.6.2
+
+* Prevent recovery of non-deleted records
+  ([#133], by [Mary Beliveau][marycodes2] and [Valerie Woolard][valeriecodes])
+* Allow model to set `table_name` after `acts_as_paranoid` macro
+  ([#131], by [Alex Wheeler][AlexWheeler])
+* Make counter cache work with a custom column name and with optional
+  associations ([#123], by [Ned Campion][nedcampion])
+
 ## 0.6.1
 
-* Add support for Rails 6 ([#124], by [Daniel Rice](danielricecodes),
-  [Josh Bryant](jbryant92), and [Romain Alexandre](RomainAlexandre))
+* Add support for Rails 6 ([#124], by [Daniel Rice][danielricecodes],
+  [Josh Bryant][jbryant92], and [Romain Alexandre][RomainAlexandre])
 * Add support for incrementing and decrementing counter cache columns on
   associated objects ([#119], by [Dimitar Lukanov][shadydealer])
 * Add `:double_tap_destroys_fully` option, with default `true` ([#116],
-  by [Michael Riviera][ri4a]).
-* Officially support Ruby 2.6 ([#114], by [Matijs van Zuijlen][mvz]).
+  by [Michael Riviera][ri4a])
+* Officially support Ruby 2.6 ([#114], by [Matijs van Zuijlen][mvz])
 
 ## 0.6.0 and earlier
 
@@ -18,15 +80,58 @@ Notable changes to this project will be documented in this file.
 
 <!-- Contributors -->
 
-[ri4a]: https://github.com/ri4a
-[mvz]: https://github.com/mvz
-[shadydealer]: https://github.com/shadydealer
+[AlexWheeler]: https://github.com/AlexWheeler
+[RomainAlexandre]: https://github.com/RomainAlexandre
+[avinoth]: https://github.com/avinoth
+[aymeric-ledorze]: https://github.com/aymeric-ledorze
 [danielricecodes]: https://github.com/danielricecodes
 [jbryant92]: https://github.com/jbryant92
-[RomainAlexandre]: https://github.com/RomainAlexandre
+[kevinmcalear]: https://github.com/kevinmcalear
+[marycodes2]: https://github.com/marycodes2
+[mvz]: https://github.com/mvz
+[nedcampion]: https://github.com/nedcampion
+[ri4a]: https://github.com/ri4a
+[pauldruziak]: https://github.com/pauldruziak
+[shadydealer]: https://github.com/shadydealer
+[soartec-lab]: https://github.com/soartec-lab
+[thebravoman]: https://github.com/thebravoman
+[valeriecodes]: https://github.com/valeriecodes
+[wtfspm]: https://github.com/wtfspm
 
 <!-- issues & pull requests -->
 
+[#209]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/209
+[#208]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/208
+[#207]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/207
+[#193]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/193
+[#191]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/191
+[#175]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/175
+[#173]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/173
+[#171]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/171
+[#170]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/170
+[#164]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/164
+[#163]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/163
+[#161]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/161
+[#160]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/160
+[#159]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/159
+[#158]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/158
+[#157]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/157
+[#156]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/156
+[#152]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/152
+[#150]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/150
+[#148]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/148
+[#147]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/147
+[#146]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/146
+[#144]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/144
+[#137]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/137
+[#136]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/136
+[#135]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/135
+[#133]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/133
+[#131]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/131
+[#126]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/126
+[#124]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/124
+[#123]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/123
 [#119]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/119
 [#116]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/116
 [#114]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/114
+[#75]: https://github.com/ActsAsParanoid/acts_as_paranoid/pull/75

data/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to ActsAsParanoid
+
+We welcome all contributions to ActsAsParanoid. Below are some guidelines to
+help the process of handling issues and pull requests go smoothly.
+
+## Issues
+
+When creating an issue, please try to provide as much information as possible.
+Also, please follow the guidelines below to make it easier for us to figure out
+what's going on. If you miss any of these points we will probably ask you to
+improve the ticket.
+
+- Include a clear title describing the problem
+- Describe what you are trying to achieve
+- Describe what you did, preferably including relevant code
+- Describe what you expected to happen
+- Describe what happened instead, possibly including relevant output
+- Use [code blocks](https://github.github.com/gfm/#fenced-code-blocks) to
+  format any code and output in your ticket to make it readable.
+
+## Pull requests
+
+If you have an idea for a particular feature, it's probably best to create a
+GitHub issue for it before trying to implement it yourself. That way, we can
+discuss the feature and whether it makes sense to include in ActsAsParanoid itself
+before putting in the work to implement it.
+
+If you want to send pull requests or patches, try to follow the instructions
+below. **If you get stuck, please make a pull request anyway and we'll try to
+help out.**
+
+- Make sure `rake test` runs without reporting any failures.
+- Add tests for your feature. Otherwise, we can't see if it works or if we
+  break it later.
+- Make sure latest master merges cleanly with your branch. Things might
+  have moved around since you forked.
+- Try not to include changes that are irrelevant to your feature in the
+  same commit.
+- Keep an eye on the build results in GitHub Actions. If the build fails and it
+  seems due to your changes, please update your pull request with a fix.
+
+### The review process
+
+- We will try to review your pull request as soon as possible but we can make no
+  guarantees. Feel free to ping us now and again.
+- We will probably ask you to rebase your branch on current master at some point
+  during the review process.
+  If you are unsure how to do this,
+  [this in-depth guide](https://git-rebase.io/) should help out.
+- If you have any unclear commit messages, work-in-progress commits, or commits
+  that just fix a mistake in a previous commits, we will ask you to clean up
+  the history.
+  Again, [the git-rebase guide](https://git-rebase.io/) should help out.
+- At the end of the review process we may still choose not to merge your pull
+  request. For example, this could happen if we decide the proposed feature
+  should not be part of ActsAsParanoid, or if the technical implementation does not
+  match where we want to go with the architecture the project.
+- We will generally not merge any pull requests that make the build fail, unless
+  it's very clearly not related to the changes in the pull request.

data/README.md

@@ -9,35 +9,38 @@ recoverable later.
 
 ## Support
 
-**This branch targets Rails 4.2, 5.0 and 5.1, with experimental support for 5.2+**
+**This branch targets Rails 5.2+ and Ruby 2.4+ only**
 
-If you're working with Rails 4.1-, switch to the corresponding branch, or
-require an older version of the `acts_as_paranoid` gem.
+If you're working with Rails 5.1 and earlier, or with Ruby 2.3 or earlier,
+please switch to the corresponding branch or require an older version of the
+`acts_as_paranoid` gem.
 
-### Known issues with Rails 5.2+
+### Known issues
 
-* Using acts_as_paranoid and ActiveStorage on the same model
+* Using `acts_as_paranoid` and ActiveStorage on the same model
   [leads to a SystemStackError](https://github.com/ActsAsParanoid/acts_as_paranoid/issues/103).
-* You cannot directly create a model in a deleted state.
+* You cannot directly create a model in a deleted state, or update a model
+  after it's been deleted.
 
 ## Usage
 
 #### Install gem:
 
-``` ruby
-gem 'acts_as_paranoid', '~> 0.6.0'
+```ruby
+gem 'acts_as_paranoid', '~> 0.7.0'
 ```
-``` shell
+
+```shell
 bundle install
 ```
 
 #### Create migration
 
-``` shell
+```shell
 bin/rails generate migration AddDeletedAtToParanoiac deleted_at:datetime:index
 ```
 
-#### Enable ActsAsParanoid:
+#### Enable ActsAsParanoid
 
 ```ruby
 class Paranoiac < ActiveRecord::Base
@@ -45,31 +48,42 @@ class Paranoiac < ActiveRecord::Base
 end
 ```
 
-The default column name and type are as follows:
-
-- `:column      => 'deleted_at'`
-- `:column_type => 'time'`
+By default, ActsAsParanoid assumes a record's *deletion* is stored in a
+`datetime` column called `deleted_at`.
 
 ### Options
 
-If you are using a different column name and type to store a record's *deletion*, you can specify them as follows:
+If you are using a different column name and type to store a record's
+*deletion*, you can specify them as follows:
 
-- `:column      => 'deleted'`
-- `:column_type => 'boolean'`
+- `column:      'deleted'`
+- `column_type: 'boolean'`
 
-While *column* can be anything (as long as it exists in your database), *type* is restricted to:
+While *column* can be anything (as long as it exists in your database), *type*
+is restricted to:
 
 - `boolean`
 - `time` or
 - `string`
 
-If your column type is a `string`, you can also specify which value to use when marking an object as deleted by passing `:deleted_value` (default is "deleted"). Any records with a non-matching value in this column will be treated normally (ie: not deleted).
+Note that the `time` type corresponds to the database column type `datetime`
+in your Rails migrations and schema.
 
-If your column type is a `boolean`, it is possible to specify `allow_nulls` option which is `true` by default. When set to `false`, entities that have `false` value in this column will be considered not deleted, and those which have `true` will be considered deleted. When `true` everything that has a not-null value will be considered deleted.
+If your column type is a `string`, you can also specify which value to use when
+marking an object as deleted by passing `:deleted_value` (default is
+"deleted"). Any records with a non-matching value in this column will be
+treated normally, i.e., as not deleted.
+
+If your column type is a `boolean`, it is possible to specify `allow_nulls`
+option which is `true` by default. When set to `false`, entities that have
+`false` value in this column will be considered not deleted, and those which
+have `true` will be considered deleted. When `true` everything that has a
+not-null value will be considered deleted.
 
 ### Filtering
 
-If a record is deleted by ActsAsParanoid, it won't be retrieved when accessing the database.
+If a record is deleted by ActsAsParanoid, it won't be retrieved when accessing
+the database.
 
 So, `Paranoiac.all` will **not** include the **deleted records**.
 
@@ -80,7 +94,8 @@ Paranoiac.only_deleted # retrieves only the deleted records
 Paranoiac.with_deleted # retrieves all records, deleted or not
 ```
 
-When using the default `column_type` of `'time'`, the following extra scopes are provided:
+When using the default `column_type` of `'time'`, the following extra scopes
+are provided:
 
 ```ruby
 time = Time.now
@@ -100,23 +115,32 @@ In order to really delete a record, just use:
 paranoiac.destroy_fully!
 Paranoiac.delete_all!(conditions)
 ```
-**NOTE:** The `.destroy!` method is still usable, but equivalent to `.destroy`. It just hides the object.
 
-Alternatively you can permanently delete a record by calling `destroy` or `delete_all` on the object **twice**.
+**NOTE:** The `.destroy!` method is still usable, but equivalent to `.destroy`.
+It just hides the object.
+
+Alternatively you can permanently delete a record by calling `destroy` or
+`delete_all` on the object **twice**.
 
-If a record was already deleted (hidden by `ActsAsParanoid`) and you delete it again, it will be removed from the database.
+If a record was already deleted (hidden by `ActsAsParanoid`) and you delete it
+again, it will be removed from the database.
 
 Take this example:
 
 ```ruby
 p = Paranoiac.first
-p.destroy # does NOT delete the first record, just hides it
-Paranoiac.only_deleted.where(:id => p.id).first.destroy # deletes the first record from the database
+
+# does NOT delete the first record, just hides it
+p.destroy
+
+# deletes the first record from the database
+Paranoiac.only_deleted.where(id: p.id).first.destroy
 ```
 
-This behaviour can be disabled by setting the configuration option. In a future version, `false` will be the default setting.
+This behaviour can be disabled by setting the configuration option. In a future
+version, `false` will be the default setting.
 
-- `:double_tap_destroys_fully => false`
+- `double_tap_destroys_fully: false`
 
 ### Recovery
 
@@ -126,34 +150,39 @@ Recovery is easy. Just invoke `recover` on it, like this:
 Paranoiac.only_deleted.where("name = ?", "not dead yet").first.recover
 ```
 
-All associations marked as `:dependent => :destroy` are also recursively recovered.
+All associations marked as `dependent: :destroy` are also recursively recovered.
 
-If you would like to disable this behavior, you can call `recover` with the `recursive` option:
+If you would like to disable this behavior, you can call `recover` with the
+`recursive` option:
 
 ```ruby
-Paranoiac.only_deleted.where("name = ?", "not dead yet").first.recover(:recursive => false)
+Paranoiac.only_deleted.where("name = ?", "not dead yet").first.recover(recursive: false)
 ```
 
-If you would like to change this default behavior for one model, you can use the `recover_dependent_associations` option
+If you would like to change this default behavior for one model, you can use
+the `recover_dependent_associations` option
 
 ```ruby
 class Paranoiac < ActiveRecord::Base
-  acts_as_paranoid :recover_dependent_associations => false
+  acts_as_paranoid recover_dependent_associations: false
 end
 ```
 
-By default, dependent records will be recovered if they were deleted within 2 minutes of the object upon which they depend.
+By default, dependent records will be recovered if they were deleted within 2
+minutes of the object upon which they depend.
 
-This restores the objects to the state before the recursive deletion without restoring other objects that were deleted earlier.
+This restores the objects to the state before the recursive deletion without
+restoring other objects that were deleted earlier.
 
-The behavior is only available when both parent and dependant are using timestamp fields to mark deletion, which is the default behavior.
+The behavior is only available when both parent and dependant are using
+timestamp fields to mark deletion, which is the default behavior.
 
 This window can be changed with the `dependent_recovery_window` option:
 
 ```ruby
 class Paranoiac < ActiveRecord::Base
   acts_as_paranoid
-  has_many :paranoids, :dependent => :destroy
+  has_many :paranoids, dependent: :destroy
 end
 
 class Paranoid < ActiveRecord::Base
@@ -161,18 +190,42 @@ class Paranoid < ActiveRecord::Base
 
   # Paranoid objects will be recovered alongside Paranoic objects
   # if they were deleted within 10 minutes of the Paranoic object
-  acts_as_paranoid :dependent_recovery_window => 10.minutes
+  acts_as_paranoid dependent_recovery_window: 10.minutes
 end
 ```
 
 or in the recover statement
 
 ```ruby
-Paranoiac.only_deleted.where("name = ?", "not dead yet").first.recover(:recovery_window => 30.seconds)
+Paranoiac.only_deleted.where("name = ?", "not dead yet").first
+  .recover(recovery_window: 30.seconds)
+```
+
+### recover!
+
+You can invoke `recover!` if you wish to raise an error if the recovery fails.
+The error generally stems from ActiveRecord.
+
+```ruby
+Paranoiac.only_deleted.where("name = ?", "not dead yet").first.recover!
+# => ActiveRecord::RecordInvalid: Validation failed: Name already exists
+```
+
+Optionally, you may also raise the error by passing `raise_error: true` to the
+`recover` method. This behaves the same as `recover!`.
+
+```ruby
+Paranoiac.only_deleted.where("name = ?", "not dead yet").first.recover(raise_error: true)
 ```
 
 ### Validation
-ActiveRecord's built-in uniqueness validation does not account for records deleted by ActsAsParanoid. If you want to check for uniqueness among non-deleted records only, use the macro `validates_as_paranoid` in your model. Then, instead of using `validates_uniqueness_of`, use `validates_uniqueness_of_without_deleted`. This will keep deleted records from counting against the uniqueness check.
+
+ActiveRecord's built-in uniqueness validation does not account for records
+deleted by ActsAsParanoid. If you want to check for uniqueness among
+non-deleted records only, use the macro `validates_as_paranoid` in your model.
+Then, instead of using `validates_uniqueness_of`, use
+`validates_uniqueness_of_without_deleted`. This will keep deleted records from
+counting against the uniqueness check.
 
 ```ruby
 class Paranoiac < ActiveRecord::Base
@@ -181,10 +234,10 @@ class Paranoiac < ActiveRecord::Base
   validates_uniqueness_of_without_deleted :name
 end
 
-p1 = Paranoiac.create(:name => 'foo')
+p1 = Paranoiac.create(name: 'foo')
 p1.destroy
 
-p2 = Paranoiac.new(:name => 'foo')
+p2 = Paranoiac.new(name: 'foo')
 p2.valid? #=> true
 p2.save
 
@@ -192,16 +245,34 @@ p1.recover #=> fails validation!
 ```
 
 ### Status
-You can check the status of your paranoid objects with the `deleted?` helper
+
+A paranoid object could be deleted or destroyed fully. 
+
+You can check if the object is deleted with the `deleted?` helper
 
 ```ruby
-Paranoiac.create(:name => 'foo').destroy
+Paranoiac.create(name: 'foo').destroy
 Paranoiac.with_deleted.first.deleted? #=> true
 ```
 
+After the first call to `.destroy` the object is `deleted?`.
+
+You can check if the object is fully destroyed with `destroyed_fully?` or `deleted_fully?`.
+
+```ruby
+Paranoiac.create(name: 'foo').destroy
+Paranoiac.with_deleted.first.deleted? #=> true
+Paranoiac.with_deleted.first.destroyed_fully? #=> false
+p1 = Paranoiac.with_deleted.first
+p1.destroy # this fully destroys the object
+p1.destroyed_fully? #=> true
+p1.deleted_fully? #=> true
+```
+
 ### Scopes
 
-As you've probably guessed, `with_deleted` and `only_deleted` are scopes. You can, however, chain them freely with other scopes you might have.
+As you've probably guessed, `with_deleted` and `only_deleted` are scopes. You
+can, however, chain them freely with other scopes you might have.
 
 For example:
 
@@ -220,10 +291,10 @@ You can work freely with scopes and it will just work:
 ```ruby
 class Paranoiac < ActiveRecord::Base
   acts_as_paranoid
-  scope :pretty, where(:pretty => true)
+  scope :pretty, where(pretty: true)
 end
 
-Paranoiac.create(:pretty => true)
+Paranoiac.create(pretty: true)
 
 Paranoiac.pretty.count #=> 1
 Paranoiac.only_deleted.count #=> 0
@@ -240,11 +311,13 @@ Paranoiac.pretty.only_deleted.count #=> 1
 
 Associations are also supported.
 
-From the simplest behaviors you'd expect to more nifty things like the ones mentioned previously or the usage of the `:with_deleted` option with `belongs_to`
+From the simplest behaviors you'd expect to more nifty things like the ones
+mentioned previously or the usage of the `:with_deleted` option with
+`belongs_to`
 
 ```ruby
 class Parent < ActiveRecord::Base
-  has_many :children, :class_name => "ParanoiacChild"
+  has_many :children, class_name: "ParanoiacChild"
 end
 
 class ParanoiacChild < ActiveRecord::Base
@@ -252,7 +325,8 @@ class ParanoiacChild < ActiveRecord::Base
   belongs_to :parent
 
   # You may need to provide a foreign_key like this
-  belongs_to :parent_including_deleted, :class_name => "Parent", :foreign_key => 'parent_id', :with_deleted => true
+  belongs_to :parent_including_deleted, class_name: "Parent",
+    foreign_key: 'parent_id', with_deleted: true
 end
 
 parent = Parent.first
@@ -263,18 +337,38 @@ child.parent #=> nil
 child.parent_including_deleted #=> Parent (it works!)
 ```
 
+### Callbacks
+
+There are couple of callbacks that you may use when dealing with deletion and
+recovery of objects. There is `before_recover` and `after_recover` which will
+be triggered before and after the recovery of an object respectively.
+
+Default ActiveRecord callbacks such as `before_destroy` and `after_destroy` will
+be triggered around `.destroy!` and `.destroy_fully!`.
+
+```ruby
+class Paranoiac < ActiveRecord::Base
+  acts_as_paranoid
+
+  before_recover :set_counts
+  after_recover :update_logs
+end
+```
+
 ## Caveats
 
 Watch out for these caveats:
 
--   You cannot use scopes named `with_deleted` and `only_deleted`
--   You cannot use scopes named `deleted_inside_time_window`, `deleted_before_time`, `deleted_after_time` **if** your paranoid column's type is `time`
--   You cannot name association `*_with_deleted`
--   `unscoped` will return all records, deleted or not
+- You cannot use scopes named `with_deleted` and `only_deleted`
+- You cannot use scopes named `deleted_inside_time_window`,
+  `deleted_before_time`, `deleted_after_time` **if** your paranoid column's
+  type is `time`
+- You cannot name association `*_with_deleted`
+- `unscoped` will return all records, deleted or not
 
 # Acknowledgements
 
-* To [Rick Olson](https://github.com/technoweenie) for creating acts_as_paranoid
+* To [Rick Olson](https://github.com/technoweenie) for creating `acts_as_paranoid`
 * To [cheerfulstoic](https://github.com/cheerfulstoic) for adding recursive recovery
 * To [Jonathan Vaught](https://github.com/gravelpup) for adding paranoid validations
 * To [Geoffrey Hichborn](https://github.com/phene) for improving the overral code quality and adding support for after_commit