README.md in audited-4.8.0 vs README.md in audited-4.9.0
- old
+ new
@@ -1,23 +1,22 @@
-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 [](http://travis-ci.org/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 can also record who made those changes, save comments and associate models related to the changes.
-Audited currently (4.x) works with Rails 5.2, 5.1, 5.0 and 4.2. It may work with 4.1 and 4.0, but this is not guaranteed.
+Audited currently (4.x) works with Rails 6.0, 5.2, 5.1, 5.0 and 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).
## Supported Rubies
Audited supports and is [tested against](http://travis-ci.org/collectiveidea/audited) the following Ruby versions:
-* 2.1.10
-* 2.2.9
-* 2.3.6
-* 2.4.3
-* 2.5.0
+* 2.3.7
+* 2.4.4
+* 2.5.1
+* 2.6.3
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
@@ -26,22 +25,24 @@
## Installation
Add the gem to your Gemfile:
```ruby
-gem "audited", "~> 4.7"
+gem "audited", "~> 4.9"
```
Then, from your Rails app directory, create the `audits` table:
```bash
$ rails generate audited:install
$ rake db:migrate
```
-If you're using PostgreSQL, then you can use `rails generate audited:install --audited-changes-column-type jsonb` (or `json`) to store audit changes natively with its JSON column types. If you're using something other than integer primary keys (e.g. UUID) for your User model, then you can use `rails generate audited:install --audited-user-id-column-type uuid` to customize the `audits` table `user_id` column type.
+By default changes are stored in YAML format. If you're using PostgreSQL, then you can use `rails generate audited:install --audited-changes-column-type jsonb` (or `json` for MySQL 5.7+ and Rails 5+) to store audit changes natively with database JSON column types.
+If you're using something other than integer primary keys (e.g. UUID) for your User model, then you can use `rails generate audited:install --audited-user-id-column-type uuid` to customize the `audits` table `user_id` column type.
+
#### Upgrading
If you're already using Audited (or acts_as_audited), your `audits` table may require additional columns. After every upgrade, please run:
```bash
@@ -65,20 +66,20 @@
By default, whenever a user is created, updated or destroyed, a new audit is created.
```ruby
user = User.create!(name: "Steve")
user.audits.count # => 1
-user.update_attributes!(name: "Ryan")
+user.update!(name: "Ryan")
user.audits.count # => 2
user.destroy
user.audits.count # => 3
```
Audits contain information regarding what action was taken on the model and what changes were made.
```ruby
-user.update_attributes!(name: "Ryan")
+user.update!(name: "Ryan")
audit = user.audits.last
audit.action # => "update"
audit.audited_changes # => {"name"=>["Steve", "Ryan"]}
```
@@ -128,11 +129,11 @@
### Comments
You can attach comments to each audit using an `audit_comment` attribute on your model.
```ruby
-user.update_attributes!(name: "Ryan", audit_comment: "Changing name, just because")
+user.update!(name: "Ryan", audit_comment: "Changing name, just because")
user.audits.last.comment # => "Changing name, just because"
```
You can optionally add the `:comment_required` option to your `audited` call to require comments for all audits.
@@ -140,10 +141,18 @@
class User < ActiveRecord::Base
audited :comment_required => true
end
```
+You can update an audit if only audit_comment is present. You can optionally add the `:update_with_comment_only` option set to `false` to your `audited` call to turn this behavior off for all audits.
+
+```ruby
+class User < ActiveRecord::Base
+ audited :update_with_comment_only => false
+end
+```
+
### Limiting stored audits
You can limit the number of audits stored for your model. To configure limiting for all audited models, put the following in an initializer:
```ruby
@@ -161,11 +170,11 @@
Whenever an object is updated or destroyed, extra audits are combined with newer ones and the old ones are destroyed.
```ruby
user = User.create!(name: "Steve")
user.audits.count # => 1
-user.update_attributes!(name: "Ryan")
+user.update!(name: "Ryan")
user.audits.count # => 2
user.destroy
user.audits.count # => 2
```
@@ -191,20 +200,20 @@
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
- post.update_attributes!(title: "Hello, world!")
+ post.update!(title: "Hello, world!")
end
post.audits.last.user # => #<User id: 1>
```
The standard Audited install assumes your User model has an integer primary key type. If this isn't true (e.g. you're using UUID primary keys), you'll need to create a migration to update the `audits` table `user_id` column type. (See Installation above for generator flags if you'd like to regenerate the install migration.)
-#### Custom Auditor
+#### Custom Audit User
-You might need to use a custom auditor from time to time. It can be done by simply passing in a string:
+You might need to use a custom auditor from time to time. This can be done by simply passing in a string:
```ruby
class ApplicationController < ActionController::Base
def authenticated_user
if current_user
@@ -214,10 +223,19 @@
end
end
end
```
+`as_user` also accepts a string, which can be useful for auditing updates made in a CLI environment:
+
+```rb
+Audited.audit_class.as_user("console-user-#{ENV['SSH_USER']}") do
+ post.update_attributes!(title: "Hello, world!")
+end
+post.audits.last.user # => 'console-user-username'
+```
+
### 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
@@ -248,11 +266,11 @@
Now, when an audit is created for a user, that user's company is also saved alongside the audit. This makes it much easier (and faster) to access audits indirectly related to a company.
```ruby
company = Company.create!(name: "Collective Idea")
user = company.users.create!(name: "Steve")
-user.update_attribute!(name: "Steve Richert")
+user.update!(name: "Steve Richert")
user.audits.last.associated # => #<Company name: "Collective Idea">
company.associated_audits.last.auditable # => #<User name: "Steve Richert">
```
You can access records' own audits and associated audits in one go:
@@ -319,9 +337,26 @@
To disable auditing on all models:
```ruby
Audited.auditing_enabled = false
+```
+
+If you have auditing disabled by default on your model you can enable auditing
+temporarily.
+
+```ruby
+User.auditing_enabled = false
+@user.save_with_auditing
+```
+
+or:
+
+```ruby
+User.auditing_enabled = false
+@user.with_auditing do
+ @user.save
+end
```
### Custom `Audit` model
If you want to extend or modify the audit model, create a new class that