Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 563 lines (368 sloc) 22.661 kb
e9a8648 Andy Stewart First commit.
airblade authored
1 # PaperTrail
2
9327083 Andy Stewart Added info on reverting and undeleting.
airblade authored
3 PaperTrail lets you track changes to your models' data. It's good for auditing or versioning. You can see how a model looked at any stage in its lifecycle, revert it to any version, and even undelete it after it's been destroyed.
e9a8648 Andy Stewart First commit.
airblade authored
4
5
6 ## Features
7
8 * Stores every create, update and destroy.
55185cd Andy Stewart Store user-defined metadata.
airblade authored
9 * Does not store updates which don't change anything.
10 * Does not store updates which only change attributes you are ignoring.
e9a8648 Andy Stewart First commit.
airblade authored
11 * Allows you to get at every version, including the original, even once destroyed.
12 * Allows you to get at every version even if the schema has since changed.
3a4187b Andy Stewart Describe version_at in README. Add JW as contributor.
airblade authored
13 * Allows you to get at the version as of a particular time.
9728e31 Andy Stewart Automatically restore has_one associations.
airblade authored
14 * Automatically restores the `has_one` associations as they were at the time.
3036aa7 Andy Stewart Store controller info. Allow other current_user methods.
airblade authored
15 * Automatically records who was responsible via your controller. PaperTrail calls `current_user` by default, if it exists, but you can have it call any method you like.
e9a8648 Andy Stewart First commit.
airblade authored
16 * Allows you to set who is responsible at model-level (useful for migrations).
3036aa7 Andy Stewart Store controller info. Allow other current_user methods.
airblade authored
17 * Allows you to store arbitrary model-level metadata with each version (useful for filtering versions).
18 * Allows you to store arbitrary controller-level information with each version, e.g. remote IP.
4f4f814 Andy Stewart Global enable/disable for PaperTrail.
airblade authored
19 * Can be turned off/on per class (useful for migrations).
20 * Can be turned off/on globally (useful for testing).
e9a8648 Andy Stewart First commit.
airblade authored
21 * No configuration necessary.
22 * Stores everything in a single database table (generates migration for you).
23 * Thoroughly tested.
9332ff2 Andy Stewart Make PaperTrail threadsafe.
airblade authored
24 * Threadsafe.
e9a8648 Andy Stewart First commit.
airblade authored
25
26
27 ## Rails Version
28
ba0d38c Andy Stewart Updated installation instructions for Rails 3.
airblade authored
29 Works on Rails 3 and Rails 2.3. Probably works on Rails 2.2 and 2.1.
e9a8648 Andy Stewart First commit.
airblade authored
30
31
bfe96a7 Andy Stewart Add API summary as a quick reference.
airblade authored
32 ## API Summary
33
34 When you declare `has_paper_trail` in your model, you get these methods:
35
36 class Widget < ActiveRecord::Base
37 has_paper_trail # you can pass various options here
38 end
39
40 # Returns this widget's versions.
41 widget.versions
42
43 # Return the version this widget was reified from, or nil if it is live.
44 widget.version
45
46 # Returns true if this widget is the current, live one; or false if it is from a previous version.
47 widget.live?
48
49 # Returns who put the widget into its current state.
50 widget.originator
51
52 # Returns the widget (not a version) as it looked at the given timestamp.
53 widget.version_at(timestamp)
54
55 # Returns the widget (not a version) as it was most recently.
56 widget.previous_version
57
58 # Returns the widget (not a version) as it became next.
59 widget.next_version
60
61 # Turn PaperTrail off for all widgets.
62 Widget.paper_trail_off
63
64 # Turn PaperTrail on for all widgets.
65 Widget.paper_trail_on
66
67 And a `Version` instance has these methods:
68
69 # Returns the item restored from this version.
70 version.reify(options = {})
71
72 # Returns who put the item into the state stored in this version.
73 version.originator
74
75 # Returns who changed the item from the state it had in this version.
76 version.terminator
77 version.whodunnit
78
79 # Returns the next version.
80 version.next
81
82 # Returns the previous version.
83 version.previous
84
85 # Returns the index of this version in all the versions.
86 version.index
87
88 # Returns the event that caused this version (create|update|destroy).
89 version.event
90
91 In your controllers you can override these methods:
92
93 # Returns the user who is responsible for any changes that occur.
94 # Defaults to current_user.
95 user_for_paper_trail
96
97 # Returns any information about the controller or request that you want
98 # PaperTrail to store alongside any changes that occur.
99 info_for_paper_trail
100
101
e9a8648 Andy Stewart First commit.
airblade authored
102 ## Basic Usage
103
4da196a Andy Stewart Expanded README.
airblade authored
104 PaperTrail is simple to use. Just add 15 characters to a model to get a paper trail of every `create`, `update`, and `destroy`.
e9a8648 Andy Stewart First commit.
airblade authored
105
106 class Widget < ActiveRecord::Base
107 has_paper_trail
108 end
109
110 This gives you a `versions` method which returns the paper trail of changes to your model.
111
112 >> widget = Widget.find 42
113 >> widget.versions # [<Version>, <Version>, ...]
114
115 Once you have a version, you can find out what happened:
116
117 >> v = widget.versions.last
118 >> v.event # 'update' (or 'create' or 'destroy')
119 >> v.whodunnit # '153' (if the update was via a controller and
120 # the controller has a current_user method,
121 # here returning the id of the current user)
122 >> v.created_at # when the update occurred
123 >> widget = v.reify # the widget as it was before the update;
124 # would be nil for a create event
125
4da196a Andy Stewart Expanded README.
airblade authored
126 PaperTrail stores the pre-change version of the model, unlike some other auditing/versioning plugins, so you can retrieve the original version. This is useful when you start keeping a paper trail for models that already have records in the database.
e9a8648 Andy Stewart First commit.
airblade authored
127
128 >> widget = Widget.find 153
129 >> widget.name # 'Doobly'
4da196a Andy Stewart Expanded README.
airblade authored
130
131 # Add has_paper_trail to Widget model.
132
e9a8648 Andy Stewart First commit.
airblade authored
133 >> widget.versions # []
134 >> widget.update_attributes :name => 'Wotsit'
135 >> widget.versions.first.reify.name # 'Doobly'
136 >> widget.versions.first.event # 'update'
137
4da196a Andy Stewart Expanded README.
airblade authored
138 This also means that PaperTrail does not waste space storing a version of the object as it currently stands. The `versions` method gives you previous versions; to get the current one just call a finder on your `Widget` model as usual.
e9a8648 Andy Stewart First commit.
airblade authored
139
140 Here's a helpful table showing what PaperTrail stores:
141
142 <table>
143 <tr>
144 <th>Event</th>
145 <th>Model Before</th>
146 <th>Model After</th>
147 </tr>
148 <tr>
149 <td>create</td>
150 <td>nil</td>
151 <td>widget</td>
152 </tr>
153 <tr>
154 <td>update</td>
155 <td>widget</td>
156 <td>widget'</td>
157 <tr>
158 <td>destroy</td>
159 <td>widget</td>
160 <td>nil</td>
161 </tr>
162 </table>
163
4da196a Andy Stewart Expanded README.
airblade authored
164 PaperTrail stores the values in the Model Before column. Most other auditing/versioning plugins store the After column.
165
166
52981bf Andy Stewart Optionally ignore attributes.
airblade authored
167 ## Ignoring changes to certain attributes
168
169 You can ignore changes to certain attributes like this:
170
171 class Article < ActiveRecord::Base
172 has_paper_trail :ignore => [:title, :rating]
173 end
174
175 This means that changes to just the `title` or `rating` will not store another version of the article. It does not mean that the `title` and `rating` attributes will be ignored if some other change causes a new `Version` to be crated. For example:
176
177 >> a = Article.create
178 >> a.versions.length # 1
179 >> a.update_attributes :title => 'My Title', :rating => 3
180 >> a.versions.length # 1
181 >> a.update_attributes :content => 'Hello'
182 >> a.versions.length # 2
183 >> a.versions.last.reify.title # 'My Title'
184
185
9327083 Andy Stewart Added info on reverting and undeleting.
airblade authored
186 ## Reverting And Undeleting A Model
4da196a Andy Stewart Expanded README.
airblade authored
187
9327083 Andy Stewart Added info on reverting and undeleting.
airblade authored
188 PaperTrail makes reverting to a previous version easy:
4da196a Andy Stewart Expanded README.
airblade authored
189
190 >> widget = Widget.find 42
9327083 Andy Stewart Added info on reverting and undeleting.
airblade authored
191 >> widget.update_attributes :name => 'Blah blah'
4da196a Andy Stewart Expanded README.
airblade authored
192 # Time passes....
9327083 Andy Stewart Added info on reverting and undeleting.
airblade authored
193 >> widget = widget.versions.last.reify # the widget as it was before the update
194 >> widget.save # reverted
195
3a4187b Andy Stewart Describe version_at in README. Add JW as contributor.
airblade authored
196 Alternatively you can find the version at a given time:
197
198 >> widget = widget.version_at(1.day.ago) # the widget as it was one day ago
199 >> widget.save # reverted
200
201 Note `version_at` gives you the object, not a version, so you don't need to call `reify`.
202
9327083 Andy Stewart Added info on reverting and undeleting.
airblade authored
203 Undeleting is just as simple:
4da196a Andy Stewart Expanded README.
airblade authored
204
9327083 Andy Stewart Added info on reverting and undeleting.
airblade authored
205 >> widget = Widget.find 42
206 >> widget.destroy
207 # Time passes....
4da196a Andy Stewart Expanded README.
airblade authored
208 >> widget = Version.find(153).reify # the widget as it was before it was destroyed
209 >> widget.save # the widget lives!
210
211 In fact you could use PaperTrail to implement an undo system, though I haven't had the opportunity yet to do it myself.
e9a8648 Andy Stewart First commit.
airblade authored
212
213
cc83502 Andy Stewart Navigate back to reified item's version.
airblade authored
214 ## Navigating Versions
215
b43400e Andy Stewart Navigate to an item's previous and next version.
airblade authored
216 You can call `previous_version` and `next_version` on an item to get it as it was/became. Note that these methods reify the item for you.
217
218 >> widget = Widget.find 42
219 >> widget.versions.length # 4 for example
220 >> widget = widget.previous_version # => widget == widget.versions.last.reify
221 >> widget = widget.previous_version # => widget == widget.versions[-2].reify
222 >> widget.next_version # => widget == widget.versions.last.reify
223 >> widget.next_version # nil
224
225 As an aside, I'm undecided about whether `widget.versions.last.next_version` should return `nil` or `self` (i.e. `widget`). Let me know if you have a view.
226
227 If instead you have a particular `version` of an item you can navigate to the previous and next versions.
cc83502 Andy Stewart Navigate back to reified item's version.
airblade authored
228
229 >> widget = Widget.find 42
230 >> version = widget.versions[-2] # assuming widget has several versions
231 >> previous = version.previous
232 >> next = version.next
233
234 You can find out which of an item's versions yours is:
235
236 >> current_version_number = version.index # 0-based
237
238 Finally, if you got an item by reifying one of its versions, you can navigate back to the version it came from:
239
240 >> latest_version = Widget.find(42).versions.last
241 >> widget = latest_version.reify
242 >> widget.version == latest_version # true
243
aa00cca Andy Stewart Add convenience method to find out if instance is live.
airblade authored
244 You can find out whether a model instance is the current, live one -- or whether it came instead from a previous version -- with `live?`:
245
246 >> widget = Widget.find 42
247 >> widget.live? # true
248 >> widget = widget.versions.last.reify
249 >> widget.live? # false
250
cc83502 Andy Stewart Navigate back to reified item's version.
airblade authored
251
e9a8648 Andy Stewart First commit.
airblade authored
252 ## Finding Out Who Was Responsible For A Change
253
4da196a Andy Stewart Expanded README.
airblade authored
254 If your `ApplicationController` has a `current_user` method, PaperTrail will store the value it returns in the `version`'s `whodunnit` column. Note that this column is a string so you will have to convert it to an integer if it's an id and you want to look up the user later on:
e9a8648 Andy Stewart First commit.
airblade authored
255
256 >> last_change = Widget.versions.last
257 >> user_who_made_the_change = User.find last_change.whodunnit.to_i
258
3036aa7 Andy Stewart Store controller info. Allow other current_user methods.
airblade authored
259 You may want PaperTrail to call a different method to find out who is responsible. To do so, override the `user_for_paper_trail` method in your controller like this:
260
261 class ApplicationController
262 def user_for_paper_trail
263 logged_in? ? current_member : 'Public user' # or whatever
264 end
265 end
266
e9a8648 Andy Stewart First commit.
airblade authored
267 In a migration or in `script/console` you can set who is responsible like this:
268
269 >> PaperTrail.whodunnit = 'Andy Stewart'
270 >> widget.update_attributes :name => 'Wibble'
271 >> widget.versions.last.whodunnit # Andy Stewart
272
f27763b Andy Stewart Clarify who was responsible for changes.
airblade authored
273 N.B. A `version`'s `whodunnit` records who changed the object causing the `version` to be stored. Because a `version` stores the object as it looked before the change (see the table above), `whodunnit` returns who stopped the object looking like this -- not who made it look like this. Hence `whodunnit` is aliased as `terminator`.
274
275 To find out who made a `version`'s object look that way, use `version.originator`. And to find out who made a "live" object look like it does, use `originator` on the object.
276
277 >> widget = Widget.find 153 # assume widget has 0 versions
278 >> PaperTrail.whodunnit = 'Alice'
279 >> widget.update_attributes :name => 'Yankee'
280 >> widget.originator # 'Alice'
281 >> PaperTrail.whodunnit = 'Bob'
282 >> widget.update_attributes :name => 'Zulu'
283 >> widget.originator # 'Bob'
284 >> first_version, last_version = widget.versions.first, widget.versions.last
285 >> first_version.whodunnit # 'Alice'
286 >> first_version.originator # nil
287 >> first_version.terminator # 'Alice'
288 >> last_version.whodunnit # 'Bob'
289 >> last_version.originator # 'Alice'
290 >> last_version.terminator # 'Bob'
291
e9a8648 Andy Stewart First commit.
airblade authored
292
9728e31 Andy Stewart Automatically restore has_one associations.
airblade authored
293 ## Has-One Associations
294
100eb53 Andy Stewart Improve automatic reification of has_one associations.
airblade authored
295 PaperTrail automatically restores `:has_one` associations as they were at (actually, 3 seconds before) the time.
9728e31 Andy Stewart Automatically restore has_one associations.
airblade authored
296
297 class Treasure < ActiveRecord::Base
298 has_one :location
299 end
300
301 >> treasure.amount # 100
302 >> treasure.location.latitude # 12.345
303
304 >> treasure.update_attributes :amount => 153
305 >> treasure.location.update_attributes :latitude => 54.321
306
307 >> t = treasure.versions.last.reify
308 >> t.amount # 100
309 >> t.location.latitude # 12.345
4cf3cb9 Andy Stewart Add caveat about has_one and transactions.
airblade authored
310
100eb53 Andy Stewart Improve automatic reification of has_one associations.
airblade authored
311 The implementation is complicated by the edge case where the parent and child are updated in one go, e.g. in one web request or database transaction. PaperTrail doesn't know about different models being updated "together", so you can't ask it definitively to get the child as it was before the joint parent-and-child update.
312
313 The correct solution is to make PaperTrail aware of requests or transactions (c.f. [Efficiency's transaction ID middleware](http://github.com/efficiency20/ops_middleware/blob/master/lib/e20/ops/middleware/transaction_id_middleware.rb)). In the meantime we work around the problem by finding the child as it was a few seconds before the parent was updated. By default we go 3 seconds before but you can change this by passing the `:has_one` option to `reify`:
314
315 >> t = treasure.versions.last.reify(:has_one => 1) # look back 1 second instead of 3
316
317 If you are shuddering, take solace from knowing you can opt out of these shenanigans:
318
319 >> t = treasure.versions.last.reify(:has_one => false) # I say no to "workarounds"!
320
321 Opting out means your `:has_one` associated objects will be the live ones, not the ones the user saw at the time. Since PaperTrail doesn't auto-restore `:has_many` associations (I can't get it to work) or `:belongs_to` (I ran out of time looking at `:has_many`), this at least makes your associations wrong consistently ;)
322
9728e31 Andy Stewart Automatically restore has_one associations.
airblade authored
323
324
f65cd0f Andy Stewart Add info and tests for has_many :through.
airblade authored
325 ## Has-Many-Through Associations
326
327 PaperTrail can track most changes to the join table. Specifically it can track all additions but it can only track removals which fire the `after_destroy` callback on the join table. Here are some examples:
328
329 Given these models:
330
331 class Book < ActiveRecord::Base
332 has_many :authorships, :dependent => :destroy
333 has_many :authors, :through => :authorships, :source => :person
334 has_paper_trail
335 end
336
337 class Authorship < ActiveRecord::Base
338 belongs_to :book
339 belongs_to :person
340 has_paper_trail # NOTE
341 end
342
343 class Person < ActiveRecord::Base
344 has_many :authorships, :dependent => :destroy
345 has_many :books, :through => :authorships
346 has_paper_trail
347 end
348
349 Then each of the following will store authorship versions:
350
351 >> @book.authors << @dostoyevsky
352 >> @book.authors.create :name => 'Tolstoy'
353 >> @book.authorships.last.destroy
354 >> @book.authorships.clear
355
356 But none of these will:
357
358 >> @book.authors.delete @tolstoy
359 >> @book.author_ids = [@solzhenistyn.id, @dostoyevsky.id]
360 >> @book.authors = []
361
312ff24 Andy Stewart Update contributors. Inline the monkey patch.
airblade authored
362 Having said that, you can apparently get all these working (I haven't tested it myself) with this [monkey patch](http://stackoverflow.com/questions/2381033/how-to-create-a-full-audit-log-in-rails-for-every-table/2381411#2381411):
363
364 # In config/initializers/core_extensions.rb or lib/core_extensions.rb
365 ActiveRecord::Associations::HasManyThroughAssociation.class_eval do
366 def delete_records(records)
367 klass = @reflection.through_reflection.klass
368 records.each do |associate|
369 klass.destroy_all(construct_join_attributes(associate))
370 end
371 end
372 end
373
374 The difference is the call to `destroy_all` instead of `delete_all` in [the original](http://github.com/rails/rails/blob/master/activerecord/lib/active_record/associations/has_many_through_association.rb#L76-81).
375
636945b Andy Stewart Add comment on association delete.
airblade authored
376
f65cd0f Andy Stewart Add info and tests for has_many :through.
airblade authored
377 There may be a way to store authorship versions, probably using association callbacks, no matter how the collection is manipulated but I haven't found it yet. Let me know if you do.
378
379
55185cd Andy Stewart Store user-defined metadata.
airblade authored
380 ## Storing metadata
381
3036aa7 Andy Stewart Store controller info. Allow other current_user methods.
airblade authored
382 You can store arbitrary model-level metadata alongside each version like this:
55185cd Andy Stewart Store user-defined metadata.
airblade authored
383
384 class Article < ActiveRecord::Base
385 belongs_to :author
0f085d1 Andy Stewart Add note about symbolds in the meta hash.
airblade authored
386 has_paper_trail :meta => { :author_id => Proc.new { |article| article.author_id },
387 :word_count => :count_words,
388 :answer => 42 }
389 def count_words
390 153
391 end
55185cd Andy Stewart Store user-defined metadata.
airblade authored
392 end
393
394 PaperTrail will call your proc with the current article and store the result in the `author_id` column of the `versions` table. (Remember to add your metadata columns to the table.)
395
396 Why would you do this? In this example, `author_id` is an attribute of `Article` and PaperTrail will store it anyway in serialized (YAML) form in the `object` column of the `version` record. But let's say you wanted to pull out all versions for a particular author; without the metadata you would have to deserialize (reify) each `version` object to see if belonged to the author in question. Clearly this is inefficient. Using the metadata you can find just those versions you want:
397
398 Version.all(:conditions => ['author_id = ?', author_id])
399
0f085d1 Andy Stewart Add note about symbolds in the meta hash.
airblade authored
400 Note you can pass a symbol as a value in the `meta` hash to signal a method to call.
401
3036aa7 Andy Stewart Store controller info. Allow other current_user methods.
airblade authored
402 You can also store any information you like from your controller. Just override the `info_for_paper_trail` method in your controller to return a hash whose keys correspond to columns in your `versions` table. E.g.:
403
404 class ApplicationController
405 def info_for_paper_trail
406 { :ip => request.remote_ip, :user_agent => request.user_agent }
407 end
408 end
409
410 Remember to add those extra columns to your `versions` table ;)
411
55185cd Andy Stewart Store user-defined metadata.
airblade authored
412
4aa1c98 Andy Stewart Add info on diffing.
airblade authored
413 ## Diffing Versions
414
e0eb4f2 Andy Stewart Remove redundant text.
airblade authored
415 When you're storing every version of an object, as PaperTrail lets you do, you're almost certainly going to want to diff those versions against each other. However I haven't built a diff method into PaperTrail because I think diffing is best left to dedicated libraries, and also it's hard to come up with a diff method to suit all the use cases.
4aa1c98 Andy Stewart Add info on diffing.
airblade authored
416
417 You might be surprised that PaperTrail doesn't use diffs internally anyway. When I designed PaperTrail I wanted simplicity and robustness so I decided to make each version of an object self-contained. A version stores all of its object's data, not a diff from the previous version.
418
419 So instead here are some specialised diffing libraries which you can use on top of PaperTrail.
420
421 For diffing two strings:
422
423 * [htmldiff](http://github.com/myobie/htmldiff): expects but doesn't require HTML input and produces HTML output. Works very well but slows down significantly on large (e.g. 5,000 word) inputs.
424 * [differ](http://github.com/pvande/differ): expects plain text input and produces plain text/coloured/HTML/any output. Can do character-wise, word-wise, line-wise, or arbitrary-boundary-string-wise diffs. Works very well on non-HTML input.
425 * [diff-lcs](http://github.com/halostatue/ruwiki/tree/master/diff-lcs/trunk): old-school, line-wise diffs.
426
427 For diffing two ActiveRecord objects:
428
429 * [Jeremy Weiskotten's PaperTrail fork](http://github.com/jeremyw/paper_trail/blob/master/lib/paper_trail/has_paper_trail.rb#L151-156): uses ActiveSupport's diff to return an array of hashes of the changes.
430 * [activerecord-diff](http://github.com/tim/activerecord-diff): rather like ActiveRecord::Dirty but also allows you to specify which columns to compare.
431
432
e9a8648 Andy Stewart First commit.
airblade authored
433 ## Turning PaperTrail Off/On
434
4f4f814 Andy Stewart Global enable/disable for PaperTrail.
airblade authored
435 Sometimes you don't want to store changes. Perhaps you are only interested in changes made by your users and don't need to store changes you make yourself in, say, a migration -- or when testing your application.
e9a8648 Andy Stewart First commit.
airblade authored
436
4f4f814 Andy Stewart Global enable/disable for PaperTrail.
airblade authored
437 If you are about change some widgets and you don't want a paper trail of your changes, you can turn PaperTrail off like this:
e9a8648 Andy Stewart First commit.
airblade authored
438
439 >> Widget.paper_trail_off
440
441 And on again like this:
442
443 >> Widget.paper_trail_on
444
4f4f814 Andy Stewart Global enable/disable for PaperTrail.
airblade authored
445 You can also disable PaperTrail for all models:
446
447 >> PaperTrail.enabled = false
448
449 For example, you might want to disable PaperTrail in your Rails application's test environment to speed up your tests. This will do it:
450
451 # in config/environments/test.rb
452 config.after_initialize do
453 PaperTrail.enabled = false
454 end
455
456 If you disable PaperTrail in your test environment but want to enable it for specific tests, you can add a helper like this to your test helper:
457
458 # in test/test_helper.rb
459 def with_versioning
460 was_enabled = PaperTrail.enabled?
461 PaperTrail.enabled = true
462 begin
463 yield
464 ensure
465 PaperTrail.enabled = was_enabled
466 end
467 end
468
469 And then use it in your tests like this:
470
471 test "something that needs versioning" do
472 with_versioning do
473 # your test
474 end
475 end
476
e9a8648 Andy Stewart First commit.
airblade authored
477
6b5c8e1 Andy Stewart Add info on deleting old versions.
airblade authored
478 ## Deleting Old Versions
479
480 Over time your `versions` table will grow to an unwieldy size. Because each version is self-contained (see the Diffing section above for more) you can simply delete any records you don't want any more. For example:
481
482 sql> delete from versions where created_at < 2010-06-01;
483
484 >> Version.delete_all ["created_at < ?", 1.week.ago]
485
486
e9a8648 Andy Stewart First commit.
airblade authored
487 ## Installation
488
ba0d38c Andy Stewart Updated installation instructions for Rails 3.
airblade authored
489 ### Rails 3
490
491 1. Install PaperTrail as a gem via your `Gemfile`:
492
493 `gem 'paper_trail'`
494
495 2. Generate a migration which will add a `versions` table to your database.
496
497 `rails generate paper_trail`
498
499 3. Run the migration.
500
501 `rake db:migrate`
502
503 4. Add `has_paper_trail` to the models you want to track.
504
505 ### Rails 2
506
af27ee5 Andy Stewart Recommend gem installation in README.
airblade authored
507 1. Install PaperTrail as a gem via your `config/environment.rb`:
e9a8648 Andy Stewart First commit.
airblade authored
508
ba0d38c Andy Stewart Updated installation instructions for Rails 3.
airblade authored
509 `config.gem 'paper_trail'`
e9a8648 Andy Stewart First commit.
airblade authored
510
edf40cd Andy Stewart Fixed typo.
airblade authored
511 2. Generate a migration which will add a `versions` table to your database.
e9a8648 Andy Stewart First commit.
airblade authored
512
0ec7261 Andy Stewart Mark down code in numbered list.
airblade authored
513 `script/generate paper_trail`
e9a8648 Andy Stewart First commit.
airblade authored
514
515 3. Run the migration.
516
0ec7261 Andy Stewart Mark down code in numbered list.
airblade authored
517 `rake db:migrate`
e9a8648 Andy Stewart First commit.
airblade authored
518
519 4. Add `has_paper_trail` to the models you want to track.
520
521
53d1758 Andy Stewart Note about the tests.
airblade authored
522 ## Testing
523
bd1877c Andy Stewart Use Bundler to manage dependencies.
airblade authored
524 PaperTrail uses Bundler to manage its dependencies (in development and testing). You can run the tests with `bundle exec rake test`. (You may need to `bundle install` first.)
53d1758 Andy Stewart Note about the tests.
airblade authored
525
526
28f05c4 Andy Stewart Link up Linx magazine article.
airblade authored
527 ## Articles
528
529 [Keep a Paper Trail with PaperTrail](http://www.linux-mag.com/id/7528), Linux Magazine, 16th September 2009.
530
531
4da196a Andy Stewart Expanded README.
airblade authored
532 ## Problems
533
534 Please use GitHub's [issue tracker](http://github.com/airblade/paper_trail/issues).
535
536
94c28e5 Andy Stewart Updated section on tests and added Contributors to README.
airblade authored
537 ## Contributors
538
539 Many thanks to:
540
541 * [Zachery Hostens](http://github.com/zacheryph)
3a4187b Andy Stewart Describe version_at in README. Add JW as contributor.
airblade authored
542 * [Jeremy Weiskotten](http://github.com/jeremyw)
9332ff2 Andy Stewart Make PaperTrail threadsafe.
airblade authored
543 * [Phan Le](http://github.com/revo)
544 * [jdrucza](http://github.com/jdrucza)
cd92392 Andy Stewart Update contributors.
airblade authored
545 * [conickal](http://github.com/conickal)
312ff24 Andy Stewart Update contributors. Inline the monkey patch.
airblade authored
546 * [Thibaud Guillaume-Gentil](http://github.com/thibaudgg)
547 * Danny Trelogan
5db477e Andy Stewart Update contributors.
airblade authored
548 * [Mikl Kurkov](http://github.com/mkurkov)
8a1fd65 Andy Stewart Update contributors.
airblade authored
549 * [Franco Catena](https://github.com/francocatena)
37f4857 Andy Stewart Add Emmanuel to list of contributors.
airblade authored
550 * [Emmanuel](https://github.com/emmanuel)
94c28e5 Andy Stewart Updated section on tests and added Contributors to README.
airblade authored
551
552
e9a8648 Andy Stewart First commit.
airblade authored
553 ## Inspirations
554
555 * [Simply Versioned](http://github.com/github/simply_versioned)
556 * [Acts As Audited](http://github.com/collectiveidea/acts_as_audited)
557
558
559 ## Intellectual Property
560
561 Copyright (c) 2009 Andy Stewart (boss@airbladesoftware.com).
562 Released under the MIT licence.
Something went wrong with that request. Please try again.