joshnabbott-active-record-versionable 0.1.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Josh N. Abbott
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,168 @@
+= ActiveRecord Versionable
+==== Version control ActiveRecord model data using Git
+
+=== WTF?
+
+Versionable is sort of a prototype gem I wrote to version control ActiveRecord model data using Git.
+
+About a year and a half ago I wrote the 'acts_as_loggable' (http://github.com/joshnabbott/acts_as_loggable) plugin which would basically create a row in the database each time a record was saved or edited with the currently logged in user's id and a time-stamp. While I had planned on adding features to store the changes using ActiveRecord's dirty objects, I never got around to doing it (if you would like to fork the project and add that functionality - you're more than welcome to! Let me know so I can apply the feature.)
+
+So a year and a half later we've been given some requirements to build a reporting platform that would allow the business to query on all sorts of data as it was during a certain period of time. For example: generate a report of all products that we were selling for < $100 between March 1, 2005 - Present. Or a report that reflects how many products were active on the site between January 1, 2008 - December 31, 2008.
+
+After thinking about these requirements a bit I really thought it sounded more like we needed a way to "version control" our model data. Effectively taking snapshots of data each time it is modified so we would:
+* Have a record of what was changed, how it was changed, and when it was changed
+* Be able to query across certain time frames and see the data reflected as it was during those time frames
+* Have the ability to instantiate an instance of the object from any snapshot so the object would be exactly what it was at that point in time.
+
+Among other things, all of those combined really added up to writing an SCM but for model data. And since I'm, well, lazy, I got to thinking: why spend months developing some sort of platform that allows us to use a database to store "snapshots" of model data, writing a bunch of utility methods that allow us to query quickly and accurately across all the data, and then actually finding the time to code the damn thing when I could just use Git?
+
+Obviously, I decided that was dumb and went for the easy way out.
+
+=== Enter Versionable
+
+Enter Versionable. It's a Ruby gem that basically uses `after_save` and `after_destroy` hooks to convert the object to yaml, write it to a file, then make a commit with the latest version of the object all with a very clear and concise commit message.
+
+By default Versionable files are stored in RAILS_ROOT + /versions, but you can specify another directory. See that below in Examples.
+
+Within the /versions directory (or whatever you end up naming your versions directory), a directory is created for each model that is Versionable. For example, if you have two models using Versionable named Article and User, you would see something like this in the versioning directory:
+  |-- versions
+      |-- articles
+      |   |-- articles.yml
+      |   |-- article-1.yml
+      |   |-- article-2.yml
+      |   `-- article-3.yml
+      `-- users
+          |-- users.yml
+          |-- user-1.yml
+          |-- user-2.yml
+          |-- user-3.yml
+          `-- user-4.yml
+
+As you may have guessed, the &lt;plural-name&gt;.yml is the most recent snapshot of each model record in yaml format. Think of it sort of like the `index` action. I'm honestly not 100% sure what this would be used for, but it seemed to make sense at the time I was writing the gem. An example of what you would see in this file is:
+  --- 
+  - !ruby/object:Person 
+    attributes: 
+      updated_at: 2009-09-23 20:57:51
+      birthdate: "1978-01-17"
+      id: "4"
+      is_living: "0"
+      age: "31"
+      name_first: Joshua
+      name_last: Abbott
+      created_at: 2009-09-23 04:15:01
+    attributes_cache: {}
+
+  - !ruby/object:Person 
+    attributes: 
+      updated_at: 2009-09-23 04:35:02
+      birthdate: "1982-05-12"
+      id: "5"
+      is_living: "1"
+      age: "27"
+      name_first: Amber
+      name_last: Jarvis
+      created_at: 2009-09-23 04:35:02
+    attributes_cache: {}
+
+  - !ruby/object:Person 
+    attributes: 
+      updated_at: 2009-09-23 06:14:22
+      birthdate: "2002-05-12"
+      id: "5"
+      is_living: "1"
+      age: "6"
+      name_first: Hayden
+      name_last: Roberts
+      created_at: 2009-09-23 06:14:22
+    attributes_cache: {}
+
+The &lt;singular_name-id&gt;.yml is the yaml representation of the current model object. An example of what you would find here is:
+  --- &id001 !ruby/object:Person 
+  attributes: 
+    updated_at: 2009-09-23 20:57:51.206652 Z
+    birthdate: 2009-01-17
+    id: "4"
+    is_living: "0"
+    age: "31"
+    name_first: Joshua
+    name_last: Abbott
+    created_at: 2009-09-23 04:15:01
+  attributes_cache: {}
+
+  changed_attributes: 
+    updated_at: 2009-09-23 20:13:51 Z
+    is_living: true
+  errors: !ruby/object:ActiveRecord::Errors 
+    base: *id001
+    errors: {}
+
+I chose to store data in YAML format because of how easy it is to use across many different programming language and platform (not the least of which is Ruby). YAML is dirt simple to read and edit and makes it easy to instantiate new ActiveRecord objects by simply loading it using `YAML::load`.
+
+=== Dependencies
+
+* Git (obviously) - http://git-scm.com/
+
+=== Installation
+
+* sudo gem install joshnabbott-active_record_versionable
+* "Versionify" your model:
+  class User < ActiveRecord::Base
+    versionify
+  end
+
+* When the model is first loaded, Versionable checks to make sure the version directories are there and that a Git repository has been initialized in the versioning directory. If directories are missing they will be created, and if there is no Git repository in the versioning directory, one will be created.
+* Don't forget to .gitignore the versioning directory unless you it and its contents being tracked by your application's SCM. It's easy to do - just type `mate .gitignore` from the root of the app and add:
+  versions/*
+* Make sure to add directory that you specified to store the Versionable versions if you're not using the default.
+
+That's it! Now you've got a versioning directory and the next time you add/edit/delete a record, you will see the version files. Versionable automatically makes your commits so you don't have to worry about a thing. In fact, unless you are dinking with the version files, you should be able to `cd` into the versioning directory at any given time, run `git status` and you should always see:
+  # On branch master
+  nothing to commit (working directory clean)
+
+=== So how about actually accessing these old 'versions' of my model data?
+
+Since the versioning directory is a separate Git repository from the one that you're using for your app (assuming you did in fact .gitignore the versioning directory), you can run any of the regular Git commands from within this directory and see your versioning data. I haven't written any additional functionality beyond just writing the model data to a file and committing it. Honestly, I don't need it yet. I know my way around Git enough that I am more than happy to just use it to play with my version controlled model data.
+
+=== Good methods to know about
+
+Custom versioning directory (please keep in mind that RAILS_ROOT is appended to this directory):
+  class Article
+    versionify :version_directory => 'tmp/versions'
+  end
+
+You can ask the class what it's version directory name is, or even get the path:
+  Article.version_dir #=> "/path/to/rails_app/tmp/versions"
+
+  Article.version_dir_name #=> versions
+
+You can also ask your ActiveRecord object for its version file like so:
+  Article.create.version_file #=> "/path/to/rails_app/tmp/versions/articles/article-4.yml"
+
+=== Some cool examples
+
+Let's say that for whatever reason you would like to instantiate an Article object from several revisions ago (let's just say you wan to do that).
+
+From command line:
+  cd /path/to/rails_app/tmp/versions/articles/
+  git checkout 123456 articles/article-4.yml
+
+From console:
+  article       = Article.find(4) #=> ActiveRecord object
+  revision_file = article.version_file #=> "/path/to/rails_app/tmp/versions/articles/article-4.yml"
+  old_article   = YAML::load(File.open(revision_file)) #=> ActiveRecord object from older version
+
+Viola! It lives. Loading an older version of the record makes it easy to see how things have changed, or what the state of a record was during a certain time.
+
+=== Parting thoughts
+
+So I realize this may or may not be the best way to write an SCM for ActiveRecord data, but for whatever reason I really wanted to do it just because I thought it would be a blast. And it has been. I'm really happy with how it's turned out so far. I haven't really got to use it in a real-life scenario yet, but I'm planning on implementing it in the next few days. It could end up turning out that this is just a total abuse of what Git should be. There are bound to be some downsides of version controlling model data this way. For one: Versionable does make heavy use of executing shell commands (for making commits and whatnot), not to mention the sheer size the Versionable repository could end up being. That really depends on how many models are being versioned, and how often data changes.
+
+It goes without saying knowing Git is sort of a pre-requisite for digging around in the revisions. Luckily, there are tons and tons of great resources on the internet that can help you become the Git ninja we all want to be. I highly recommend learning the hell out of `git log` and `git diff` if you really want to do some impressive stuff.
+
+== Contributing
+
+I'd love all the help I can get on Versionable. If you have any really cool ideas, please feel free to fork the source and let me know when you have a feature you'd like me to check out!
+
+== License
+
+Copyright (c) 2009 Josh N. Abbott (http://iammrjoshua.com), released under the MIT license

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "active-record-versionable"
+    gem.summary = %Q{Version control ActiveRecord model data}
+    gem.description = %Q{Makes version controlling ActiveRecord model data easy and powerful.}
+    gem.email = "joshnabbott@gmail.com"
+    gem.homepage = "http://github.com/joshnabbott/active-record-versionable"
+    gem.authors = ["Josh N. Abbott"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "active-record-versionable #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/active-record-versionable.gemspec

@@ -0,0 +1,52 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{active-record-versionable}
+  s.version = "0.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Josh N. Abbott"]
+  s.date = %q{2009-09-23}
+  s.description = %q{Makes version controlling ActiveRecord model data easy and powerful.}
+  s.email = %q{joshnabbott@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "active-record-versionable.gemspec",
+     "init.rb",
+     "lib/active_record_versionable.rb",
+     "rails/init.rb",
+     "test/active_record_versionable_test.rb",
+     "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/joshnabbott/active-record-versionable}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Version control ActiveRecord model data}
+  s.test_files = [
+    "test/active_record_versionable_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'rails/init'

data/lib/active_record_versionable.rb

@@ -0,0 +1,140 @@
+module ActiveRecordVersionable
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    def versionify(options = {})
+      options.reverse_merge!(:version_directory => "#{RAILS_ROOT}/versions")
+      setup!(options)
+      send(:include, ActiveRecord::Versionable::InstanceMethods)
+      after_destroy :version!
+      after_save :version!
+
+      instance_eval do
+        def commit!(message = Time.now.to_s)
+          response = `cd #{self.version_dir} && git add . && git commit -am '#{message}'`
+
+          logger.debug("#### START VERSIONING ####")
+          logger.debug(response)
+          # logger.debug $?
+          logger.debug("#### END VERSIONING ####")
+        end
+
+        def version
+          File.open(self.version_file, 'w+') { |file| file.write(self.all.to_yaml) }
+        end
+
+        def version_dir
+          @@version_dir
+        end
+
+        def version_dir=(directory)
+          @@version_dir = directory
+        end
+
+        def version_dir_name
+          @@version_dir_name
+        end
+
+        def version_dir_name=(directory_name)
+          @@version_dir_name = directory_name
+        end
+
+        def version_file
+          File.join(self.version_dir, self.class_name.tableize, self.version_file_name)
+        end
+
+        def version_file_name
+          "#{self.class_name.tableize}.yml"
+        end
+
+        def unversion!
+          File.delete(version_file)
+          self.all.map(&:unversion!)
+          self.commit!("No longer version controlling #{self.class_name}.")
+        end
+
+        private
+          def create_version_directories!
+            Dir.mkdir(self.version_dir) unless File.exists?(self.version_dir)
+            Dir.mkdir(File.join(self.version_dir, self.class_name.tableize)) unless File.exists?(File.join(self.version_dir, self.class_name.tableize))
+          end
+
+          def initialize_git_repository!
+            unless File.exists?(File.join(self.version_dir, '.git'))
+              response = `cd #{self.version_dir} && git init`
+
+              logger.debug("#### START INITIALIZING GIT REPOSITORY ####")
+              logger.debug(response)
+              # logger.debug $?
+              logger.debug("#### END INITIALIZING GIT REPOSITORY ####")
+            end
+          end
+
+          def setup_complete?
+            File.exists?(self.version_dir) &&
+            File.exists?(File.join(self.version_dir, self.class_name.tableize)) &&
+            File.exists?(File.join(self.version_dir, '.git'))
+          end
+
+          # Create the necessary directories and files, along with initializing a new git repo when needed
+          def setup!(options)
+            self.version_dir      = options[:version_directory]
+            self.version_dir_name = options[:version_directory].split('/').last
+            unless setup_complete?
+              create_version_directories!
+              initialize_git_repository!
+              STDOUT.puts "***************** IMPORTANT *****************"
+              STDOUT.puts "Versionable has created a new direcotry in #{self.version_dir} where files will be written to and stored."
+              STDOUT.puts "Since you may not want Git tracking the files Versionable creates, you may want to add #{self.version_dir_name}/* to your .gitignore file."
+              STDOUT.puts "If you don't already have a .gitignore file in #{RAILS_ROOT} (#{File.exists?(File.join(RAILS_ROOT, '.gitignore')) ? "and you do" : "which you don't"}) you may want to create one now."
+            end
+          end
+      end
+    end
+  end
+
+  module InstanceMethods
+    def version!
+      self.class.version
+      self.version
+      self.class.commit!(calculate_commit_message)
+    end
+
+    def version
+      File.open(self.version_file, 'w+') { |file| file.write(self.to_yaml) }
+    end
+
+    def version_file
+      File.join(self.class.version_dir, self.class.class_name.tableize, version_file_name)
+    end
+
+    def version_file_name
+      "#{self.class.class_name.downcase.underscore}-#{self.id}.yml"
+    end
+
+    def unversion!
+      File.delete(version_file)
+    end
+
+    protected
+      def calculate_commit_message
+        # Using after_save and after_destroy means there are three possibilities:
+        # The record was either inserted, updated, or deleted from the db.
+        # We can find out if it was deleted by simply seeing if the record still exists in the db.
+        # However, finding out whether the record was inserted or updated is trickier since Class#new_record? returns
+        # false after save.
+        # The best thing I came up with was checking to see if the instance variable @new_record is still hanging around for this instance
+        # If it is, that means the record was just created. If it's not, it was updated.
+        action = if !self.instance_variable_get("@new_record").nil?
+          'Created'
+        elsif !self.class.exists?(self.id)
+          'Deleted'
+        else
+          'Updated'
+        end
+        "#{action} #{self.class.class_name}[#{self.id}]: #{Time.now.to_s(:db)}"
+      end
+  end
+end

data/rails/init.rb

@@ -0,0 +1,2 @@
+require 'active_record_versionable'
+ActiveRecord::Base.instance_eval { include ActiveRecordVersionable }

data/test/active_record_versionable_test.rb

@@ -0,0 +1,7 @@
+require 'test_helper'
+
+class ActiveRecordVersionableTest < Test::Unit::TestCase
+  should "probably rename this file and start testing for real" do
+    flunk "hey buddy, you should probably rename this file and start testing for real"
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'active_record_versionable'
+
+class Test::Unit::TestCase
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: joshnabbott-active-record-versionable
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Josh N. Abbott
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-23 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Makes version controlling ActiveRecord model data easy and powerful.
+email: joshnabbott@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- active-record-versionable.gemspec
+- init.rb
+- lib/active_record_versionable.rb
+- rails/init.rb
+- test/active_record_versionable_test.rb
+- test/test_helper.rb
+has_rdoc: false
+homepage: http://github.com/joshnabbott/active-record-versionable
+licenses: 
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Version control ActiveRecord model data
+test_files: 
+- test/active_record_versionable_test.rb
+- test/test_helper.rb