#Introduction
A simple gem for adding versioning to your CouchRest::Model::Base documents. When you update a document, the previous version gets stored as an attachment on the document. This versioning strategy was originally created here: http://blog.couch.io/post/632718824/simple-document-versioning-with-couchdb
##Installation
$ gem install memories
Documentation
Browse the documentation on rubydoc.info: http://rubydoc.info/gems/memories/frames
##How does it work?
Just "include Memories" in your "CouchRest::Model::Base" classes and let the auto-versioning begin.
###Basic Versioning
Here's how basic versioning works. Every time you save your document, you get a new version. You have the ability to roll back to a previous version.
class Book < CouchRest::Model::Base
include Memories
use_database SOME_DATABASE
property :name
view_by :name
end
b = Book.create :name => "2001"
b.current_version #==> 1
b.name = "2001: A Space Odyssey"
b.save
b.current_version #==> 2
b.previous_version #==> 1
b.name #==> "2001: A Space Odyssey"
b.revert_to! 1
b.name #==> "2001"
b.current_version #==> 3
If you'd like to exclude certain properties from versioning, use the #forget class method:
class Book < CouchRest::Model::Base
include Memories
use_database SOME_DATABASE
forget :notes
property :name
property :notes
view_by :name
end
b = Book.create :name => "2001", :notes => "creating the book."
b.current_version #==> 1
b.name = "2001: A Space Odyssey"
b.notes += "updating the title. might ship today. 9/2/2010. MKP"
b.save
b.current_version #==> 2
b.previous_version #==> 1
p b.name #==> "2001: A Space Odyssey"
p b.notes # ==> "creating the book. updating the title. might ship today. 9/2/2010. MKP"
b.revert_to! 1
p b.name #==> "2001"
p b.notes # ==> "creating the book. updating the title. might ship today. 9/2/2010. MKP"
b.current_version #==> 3
If you'd like to explicitly define which properties to version, use the #remember method. It works just like #forget, but in reverse. Duh.
###Milestones
As of version 0.2.0, Memories also supports milestones. Milestones are special versions that you want to flag in some way. For example, suppose you were creating a content management system, and every time someone publishes an article to the website, you want to flag the version they published as a milestone.
class Article < CouchRest::Model::Base
include Memories
use_database SOME_DATABASE
property :title
property :author
property :body
def publish!
# .... publishing logic
end
end
a = Article.create(
:title => "Memories gem makes versioning simple",
:author => "moonmaster9000",
:body => <<-ARTICLE
Check it out at http://github.com/moonmaster9000/memories
ARTICLE
)
a.save
a.publish!
a.current_version #==> 1
a.milestone! do
name "First publish."
notes "Passed all relevant editing. Signed off by moonmaster10000"
end
Notice that we annotated our milestone; we gave it a name, and some notes. You can annotate with whatever properties you desire. The annotation do block is entirely optional.
Now that we've created a milestone, let's inspect it via the milestones array:
a.milestones.count #==> 1
a.milestones.last.version # ==> 'rev-1-893428ifldlfds9832'
a.milestones.last.version_number # ==> 1
a.milestones.last.annotations.name # ==> "First publish."
a.milestones.last.annotations.notes # ==> "Passed all relevant editing. Signed off by moonmaster 10000"
a.milestones.last.instance.title # ==> Memories gem makes versioning simple
Now, let's imagine that we've made some more edits / saves to the document, but they don't get approved. Now we want to revert to the version the document was at at the first milestone. How do we do that? Simple!
a.revert_to_milestone! 1
And now our document properties are back to the where they were when we first published the document.
If you want to access the version instance of a milestone, simply use the "instance" method:
a.milestones.first.instance.title #==> returns the "title" attribute on the first milestone
a.milestones.each do |m|
puts "Version: " + m.version
puts "Title: " + m.instance.title
end
Attachments
By default, memories doesn't version attachments. If you'd like to version attachments, simply call the remember_attachments! class method in your
class definition:
class MyDoc < CouchRest::Model::Base
use_database MY_DB
include Memories
remember_attachments!
end
If you only want specific attachments versioned, pass strings and/or regular expressions to this macro. Any attachments with matching names will be versioned.
class HtmlPage < CouchRest::Model::Base
use_database MY_DB
include Memories
remember_attachments! "image.png", %r{stylesheets/.*}
end
Accessing Previous Versions
You can access old versions of your document via the "versions" method; it will return a proxy with array-like and hash-like access to previous versions.
@doc.versions[1].instance # ==> returns version 1 of your document
@doc.versions[1].revision # ==> 'rev-1-jkfldsi32849032894032'
@doc.versions[1].version_number # ==> 1
@doc.versions['rev-1-kjfdsla3289430289432'].instance # ==> returns version 1 of your document
@doc.versions[1..7] # ==> returns version proxies 1 through 7 of your document
@doc.versions.count # ==> returns the number of versions of your document
@doc.versions.last # ==> returns a proxy for the latest version of your document
@doc.versions.first # ==> returns a proxy for the first version of your document
@doc.versions.each do |v|
puts v.instance.some_property
end
Logical Revision Numbers
As of version 0.3.1, when you soft revert a document (#revert_to), you can access the logical revision and logical version numbers of that document.
For example, suppose you soft revert a document with 10 versions to version 2.
@doc.current_version # ==> 10
@doc.revert_to 2
When you ask the logical revision, you'll receive the revision number of version 2:
@doc.logical_revision #==> 'rev-2-kfdlsa432890432890432'
Similarly, the logical version number:
@doc.logical_version_number #==> 2
However, as soon as you save the document, the logical revision and logical version number will simply mirror those of the actual document
@doc.save
@doc.rev #==> '11-qwerty1234567890'
@doc.logical_revision #==> 'rev-11-qwerty1234567890'
@doc.logical_version_number #==> 11