= acts_as_audited

+acts_as_audited+ is an ActiveRecord extension that logs all changes to your 
models in an audits table, with optional revision comments. +acts_as_audited+
has been updated to work with Rails 3, to use it with older version of Rails,
please see the <tt>1.1-stable</tt> branch.

== Installation

In <tt>Gemfile</tt>:

    gem "acts_as_audited", "2.0.0.rc5"

In your application root, run:

    $ bundle install

Generate the migration:

* If installing without a previous version of +acts_as_audited+ or you do not mind overwriting your audits table:

    $ rails g acts_as_audited:install

* If upgrading from a previous version of +acts_as_audited+ you might need some alterations to the audits table:

    $ rails g acts_as_audited:upgrade

* After running one of the generators:

    $ rake db:migrate

== Rails deprecation warning

Currently the gem causes the following deprecation warning to be emitted:

    DEPRECATION WARNING: reorder is deprecated. Please use except(:order).order(...) instead. (called from <class:Audit> at /Users/kenneth/Code/FOSS/acts_as_audited/lib/acts_as_audited/audit.rb:26)

I'm well aware of the fact, and working towards a solution. The issue has also been brought up on the Rails lighthouse as #6011[https://rails.lighthouseapp.com/projects/8994/tickets/6011-exceptorderorder-is-not-working-in-scopes]. I'm keeping an eye on the issue and working towards another possible solution.

== Upgrading

Upgrading to Rails 3, or even between point releases of +acts_as_audited+, might require alterations to the audits table. After every upgrade please run the following generator:

    $ rails g acts_as_audited:upgrade

The upgrade generator will only generate migrations that are missing, or no migrations at all if you are up to date.

== Usage

Declare +acts_as_audited+ on your models:

    class User < ActiveRecord::Base
      acts_as_audited :except => [:password, :mistress]
    end

Within a web request, will automatically record the user that made the change if your controller has a +current_user+ method. Comments can be added to an audit by setting <tt>model.audit_comments</tt> 
before create/update/destroy. If the <tt>:comment_required</tt> option is given to +acts_as_audited+, 
the save/update/destroy action will fail with add an error on <tt>model.audit_comment</tt> and triggering a 
transaction rollback if <tt>model.audit_comment</tt> is nil.

To record an audit for an associated model, use the <tt>:associated_with</tt> option.

    class User < ActiveRecord::Base
      acts_as_audited :associated_with => :company
    end

If desired, the associated model can access its audits using <tt>has_associated_audits</tt>.

    class Company < ActiveRecord::Base
      has_many :users
      has_associated_audits
    end

To record a user in the audits outside of a web request, you can use +as_user+:

    Audit.as_user(user) do
      # Perform changes on audited models
    end

== Caveats

If your model declares +attr_accessible+ after +acts_as_audited+, you need to set <tt>:protect</tt> to false. acts_as_audited uses +attr_protected+ internally to prevent malicious users from unassociating your audits, and Rails does not allow both +attr_protected+ and +attr_accessible+. It will default to false if +attr_accessible+ is called before +acts_as_audited+, but needs to be explicitly set if it is called after.

  class User < ActiveRecord::Base
    acts_as_audited :protect => false
    attr_accessible :name
  end

Another caveat is documented in issue 26[https://github.com/collectiveidea/acts_as_audited/issues#issue/26], where an audit created on the first request to the server does not have a user. Please review the Github issue for more details on how to fix this. It does not appear to affect Rails 3.

== Compatability

+acts_as_audited+ works with Rails 3.0.3. For older versions of Rails, please see the <tt>1.1-stable</tt> branch.

== Getting Help

Review the documentation at http://rdoc.info/github/collectiveidea/acts_as_audited

Join the mailing list for getting help or offering suggestions - http://groups.google.com/group/acts_as_audited

== Branches

The <tt>master</tt> branch is considered stable, and you should be able to use it at any time. The <tt>development</tt> branch will contain all active development and might be a moving target from time to time.

== Contributing

Contributions are always welcome. Checkout the latest code on GitHub - http://github.com/collectiveidea/acts_as_audited

When contributing a bug-fix, please use a topic branch created off our <tt>master</tt> branch. When developing a new feature, please create a topic branch of our <tt>development</tt> branch (and rebase before submiting a pull request).

Please include tests with your patches. There are a few gems required to run the tests:

  $ bundle install

Make sure the tests pass against the version of Rails specified in the Gemfile

  $ rake spec test

Please report bugs or feature suggestions on GitHub - http://github.com/collectiveidea/acts_as_audited/issues