README.md in audited-4.2.2 vs README.md in audited-4.3.0
- old
+ new
@@ -1,39 +1,39 @@
-Audited [](http://travis-ci.org/collectiveidea/audited) [](https://gemnasium.com/collectiveidea/audited)[](https://codeclimate.com/github/collectiveidea/audited)
+Audited [](http://travis-ci.org/collectiveidea/audited) [](https://gemnasium.com/collectiveidea/audited)[](https://codeclimate.com/github/collectiveidea/audited) [](https://hakiri.io/github/collectiveidea/audited/master)
=======
-**Audited** (previously acts_as_audited) is an ORM extension that logs all changes to your models. Audited also allows you to record who made those changes, save comments and associate models related to the changes.
+**Audited** (previously acts_as_audited) is an ORM extension that logs all changes to your models. Audited can also record who made those changes, save comments and associate models related to the changes.
-Audited currently (4.x) works with Rails 4.2. For Rails 3, use gem version 3.0 or see the [3.0-stable branch](https://github.com/collectiveidea/audited/tree/3.0-stable).
+Audited currently (4.x) works with Rails 5.0 and 4.2. It may work with 4.1 and 4.0, but this is not guaranteed.
+For Rails 3, use gem version 3.0 or see the [3.0-stable branch](https://github.com/collectiveidea/audited/tree/3.0-stable).
+
## Supported Rubies
Audited supports and is [tested against](http://travis-ci.org/collectiveidea/audited) the following Ruby versions:
-* 2.0.0
* 2.1.5
-* 2.2.0
+* 2.2.4
+* 2.3.1
Audited may work just fine with a Ruby version not listed above, but we can't guarantee that it will. If you'd like to maintain a Ruby that isn't listed, please let us know with a [pull request](https://github.com/collectiveidea/audited/pulls).
## Supported ORMs
-In a previous life, Audited was ActiveRecord-only. Audited will now audit models for the following backends:
+Audited is currently ActiveRecord-only. In a previous life, Audited worked with MongoMapper. Use the [4.2-stable branch](https://github.com/collectiveidea/audited/tree/4.2-stable) if you need MongoMapper.
-* ActiveRecord
-* MongoMapper
-
## Installation
-The installation process depends on what ORM your app is using.
+Add the gem to your Gemfile:
-### ActiveRecord
+```ruby
+gem "audited", "~> 4.3"
+```
-Add the appropriate gem to your Gemfile:
-
+If you are using rails 5.0, you would also need the following line in your Gemfile.
```ruby
-gem "audited-activerecord", "~> 4.0"
+gem "rails-observers", github: 'rails/rails-observers'
```
Then, from your Rails app directory, create the `audits` table:
```bash
@@ -50,16 +50,11 @@
$ rake db:migrate
```
Upgrading will only make changes if changes are needed.
-### MongoMapper
-```ruby
-gem "audited-mongo_mapper", "~> 4.0"
-```
-
## Usage
Simply call `audited` on your models:
```ruby
@@ -86,10 +81,19 @@
audit = user.audits.last
audit.action # => "update"
audit.audited_changes # => {"name"=>["Steve", "Ryan"]}
```
+You can get previous versions of a record by index or date, or list all
+revisions.
+
+```ruby
+user.revisions
+user.revision(1)
+user.revision_at(Date.parse("2016-01-01"))
+```
+
### Specifying columns
By default, a new audit is created for any attribute changes. You can, however, limit the columns to be considered.
```ruby
@@ -141,11 +145,11 @@
### Current User Tracking
If you're using Audited in a Rails application, all audited changes made within a request will automatically be attributed to the current user. By default, Audited uses the `current_user` method in your controller.
-```
+```ruby
class PostsController < ApplicationController
def create
current_user # => #<User name: "Steve">
@post = Post.create(params[:post])
@post.audits.last.user # => #<User name: "Steve">
@@ -160,16 +164,32 @@
```
Outside of a request, Audited can still record the user with the `as_user` method:
```ruby
-Audited.audit_class.as_user(User.find(1)) do
+Audited::Audit.as_user(User.find(1)) do
post.update_attribute!(title: "Hello, world!")
end
post.audits.last.user # => #<User id: 1>
```
+#### Custom Auditor
+
+You might need to use a custom auditor from time to time. It can be done by simply passing in a string:
+
+```ruby
+class ApplicationController < ActionController::Base
+ def authenticated_user
+ if current_user
+ current_user
+ else
+ 'Elon Musk'
+ end
+ end
+end
+```
+
### Associated Audits
Sometimes it's useful to associate an audit with a model other than the one being changed. For instance, given the following models:
```ruby
@@ -238,37 +258,30 @@
User.auditing_enabled = false
```
## Gotchas
-### Using attr_protected or strong_parameters
+### Using attr_protected with Rails 4.x
-Audited assumes you are using `attr_accessible`. If you're using
-`attr_protected` or `strong_parameters`, you'll have to take an extra step or
-two.
+If you're using the `protected_attributes` gem with Rails 4.0, 4.1 or 4.2 (the gem isn't supported in Rails 5.0 or higher), you'll have to take an extra couple of steps to get `audited` working.
+First be sure to add `allow_mass_assignment: true` to your `audited` call; otherwise Audited will
+interfere with `protected_attributes` and none of your `save` calls will work.
-If you're using `strong_parameters` with Rails 3.x, be sure to add `allow_mass_assignment: true` to your `audited` call; otherwise Audited will
-interfere with `strong_parameters` and none of your `save` calls will work.
-
```ruby
class User < ActiveRecord::Base
audited allow_mass_assignment: true
end
```
-If using `attr_protected`, add `allow_mass_assignment: true`, and also be sure to add `audit_ids` to the list of protected attributes to prevent data loss.
+Second, be sure to add `audit_ids` to the list of protected attributes to prevent data loss.
```ruby
class User < ActiveRecord::Base
audited allow_mass_assignment: true
attr_protected :logins, :audit_ids
end
```
-
-### MongoMapper Embedded Documents
-
-Currently, Audited does not track changes on embedded documents. Audited works by tracking a model's [dirty changes](http://api.rubyonrails.org/classes/ActiveModel/Dirty.html) but changes to embedded documents don't appear in dirty tracking.
## Support
You can find documentation at: http://rdoc.info/github/collectiveidea/audited