active_versioning 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 372e09adffd4d458bf02a8f21790b4c0545c3654
+  data.tar.gz: d7d12be88770e3731fcda71a38dc8ccdee72ab50
+SHA512:
+  metadata.gz: 7e60a689e0bb675c81617a4c1f585e2a7e9c609603608cb29aa2301af76c2d4586b91104d9cc20d7686e6730442fd472958d79a197cca27373f5a8d9322026b2
+  data.tar.gz: e9b46b96aade3689dddcd4de01b089d75316e8c478d129e2e9a71d31abd613b5b177230cd8de9f9e4a3095be2ac48ee3ff09df6e41f564ac2cd27c77912632c3

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.2
+before_install: gem install bundler -v 1.10.3

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in active_versioning.gemspec
+gemspec

data/README.md

@@ -0,0 +1,140 @@
+# ActiveVersioning
+
+[![Gem Version](https://badge.fury.io/rb/active_versioning.svg)](http://badge.fury.io/rb/active_versioning) [![Code Climate](https://codeclimate.com/github/vigetlabs/active_versioning/badges/gpa.svg)](https://codeclimate.com/github/vigetlabs/active_versioning) [![Test Coverage](https://codeclimate.com/github/vigetlabs/active_versioning/badges/coverage.svg)](https://codeclimate.com/github/vigetlabs/active_versioning/coverage) [![Circle CI](https://circleci.com/gh/vigetlabs/active_versioning.svg?style=svg)](https://circleci.com/gh/vigetlabs/active_versioning)
+
+ActiveVersioning provides out-of-the-box versioning functionality in Rails.  ActiveVersioning serializes attributes when records are saved and allows for version and draft management.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_versioning'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install active_versioning
+
+Once installed, generate the necessary files and run migrations:
+
+    $ rails generate active_versioning
+    $ bundle exec rake db:migrate
+
+## Setup
+
+To set up versioning in your Rails app, include the following module in each model you'd like to version:
+```ruby
+class Post < ActiveRecord::Base
+  include ActiveVersioning::Model::Versioned
+end
+```
+
+## Working with Drafts
+
+`ActiveVersioning::Model::Versioned` provides a number of methods for accessing and working with versions.
+
+To access the current draft of a record, use...
+```ruby
+draft = post.current_draft
+```
+This returns a proxy object to a draft version of the record, so you can treat it like the `post` itself -- making changes and either saving or updating.
+```ruby
+draft.title = 'New Title'
+draft.save
+
+# or..
+
+draft.update(title: 'New Title')
+```
+Both `save` and `update` will make changes to the draft version of the post.
+
+When you are ready to overwrite the record with its draft, use...
+```ruby
+draft.commit(committer: 'Bob', commit_message: 'Update post title.')
+```
+This changes our post's attributes to match those of the draft and then marks the draft as a committed version.
+
+If you want to throw away a draft:
+```ruby
+post.destroy_draft
+```
+
+## Working with Versions
+
+A draft is just a version with a particular state.  To access all the versions for a particular record, use...
+```ruby
+post.versions              # => All versions, whether the version state is 'create', 'draft', or 'commit'
+post.versions.draft        # => All draft versions
+post.versions.committed    # => All non-draft versions
+post.versions.newest_first # => All versions starting with the most recently created
+```
+
+You can use any existing version to create a new draft:
+```ruby
+old_version = post.versions.committed.first
+
+post.create_draft_from_version(old_version.id)
+```
+This will set `post.current_draft`'s attributes to the attributes stored in the given version's record. Returns boolean based on the save's success.
+
+## Capturing Version Metadata
+
+In addition to manually committing a version with a committer and commit message...
+```ruby
+post.current_draft.commit(committer: 'Bob', commit_message: 'Update post title.')
+```
+ActiveVersioning provides a `version_author` accessor on any versioned model, so you can capture the author for a record's initial create:
+```ruby
+post = Post.create(title: 'Title', body: 'Body text.', version_author: 'Bob')
+
+post.versions.first.version_author # => 'Bob'
+```
+
+## Viewing and Modifying Versioned Attributes
+
+If you want to see the attributes the are versioned, use...
+```ruby
+post.versioned_attributes # => { 'id' => 1, 'title' => 'Default Title' }
+```
+
+If you require additional versioned attributes, overwrite the `versioned_attribute_names` method in your model:
+```ruby
+class Post < ActiveRecord::Base
+  private
+
+  def versioned_attribute_names
+   super + %w(photo_id)
+  end
+end
+```
+
+## Handling Incompatible Versions
+
+In the case of a versioned model that undergoes a schema change, all previous versions may reference attributes that no longer exist.
+
+In ActiveVersioning, we consider these incompatible versions.  An attempt to create a draft from an incompatible version will raise an error:
+```
+incompatible_version = post.versions.committed.last
+
+incompatible_version.object
+# => { 'deleted_attribute' => value }
+
+post.create_draft_from_version(incompatible_version.id)
+# => ActiveVersioning::Errors::IncompatibleVersion:
+# The given version contains attributes that are no longer compatible with the current schema: deleted_attribute.
+```
+
+When rescued, the error object contains a reference to the record and the incompatible version:
+```
+begin
+  post.create_draft_from_version(incompatible_version.id)
+rescue ActiveVersioning::Errors::IncompatibleVersion => error
+  error.record  # => our `post` record
+  error.version # => our `incompatible_version`
+end
+```

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/active_versioning.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'active_versioning/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "active_versioning"
+  spec.version       = ActiveVersioning::VERSION
+  spec.authors       = ["Ryan Stenberg"]
+  spec.email         = ["ryan.stenberg@viget.com"]
+
+  spec.summary       = "Plug-and-Play Versioning for Rails"
+  spec.description   = "ActiveVersioning serializes attributes when records are saved and allows for version and draft management."
+  spec.homepage      = "https://github.com/vigetlabs/active_versioning"
+  spec.license       = "BSD"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rails", ">= 4.2.1"
+
+  spec.add_development_dependency "bundler", ">= 1.10"
+  spec.add_development_dependency "rake", ">= 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "shoulda-matchers"
+  spec.add_development_dependency "database_cleaner"
+  spec.add_development_dependency "generator_spec"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "codeclimate-test-reporter"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "active_versioning"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/circle.yml

@@ -0,0 +1,6 @@
+database:
+  override:
+    - echo "No database setup necessary."
+dependencies:
+  pre:
+    - gem install bundler --pre

data/lib/active_versioning/errors/incompatible_version.rb

@@ -0,0 +1,12 @@
+module ActiveVersioning
+  module Errors
+    class IncompatibleVersion < StandardError
+      attr_reader :record, :version
+
+      def initialize(record, version)
+        @record  = record
+        @version = version
+      end
+    end
+  end
+end

data/lib/active_versioning/errors.rb

@@ -0,0 +1,8 @@
+module ActiveVersioning
+  module Errors
+    autoload :IncompatibleVersion, 'active_versioning/errors/incompatible_version'
+
+    RecordNotPersisted = Class.new(StandardError)
+    InvalidVersion     = Class.new(StandardError)
+  end
+end

data/lib/active_versioning/events.rb

@@ -0,0 +1,13 @@
+module ActiveVersioning
+  module Events
+    CREATE = 'create'
+    DRAFT  = 'draft'
+    COMMIT = 'commit'
+
+    ALL = [
+      CREATE,
+      DRAFT,
+      COMMIT
+    ]
+  end
+end

data/lib/active_versioning/model/version_proxy.rb

@@ -0,0 +1,119 @@
+module ActiveVersioning
+  module Model
+    class VersionProxy < Delegator
+      #
+      # VersionProxy class
+      #
+      # Uses Ruby's Delegator class to delegate methods to the versioned
+      # resource.  The bulk of this class overrides the Rails save, update, and
+      # reload methods to modify the record in the versions table as opposed
+      # to the versioned resource.
+      #
+      # A `commit` instance method writes to the versioned resource's record.
+
+      VersionInvalid = Class.new(StandardError)
+
+      attr_reader :version
+
+      def initialize(version)
+        @version = version
+        __setobj__(version.reify)
+      end
+
+      def __getobj__
+        @record
+      end
+
+      def __setobj__(record)
+        @record = record
+      end
+
+      # `class` should delegate to versioned resource, not return
+      # ActiveVersioning::Model::VersionProxy
+      undef class
+
+      def reload
+        __setobj__(version.reify)
+      end
+
+      def to_param
+        version.versionable.to_param
+      end
+
+      def save(*)
+        if valid?
+          version.update(version_attributes)
+        else
+          false
+        end
+      end
+
+      def save!(*)
+        if valid?
+          version.update!(version_attributes)
+        else
+          raise ::ActiveRecord::RecordInvalid.new(__getobj__)
+        end
+      end
+
+      def update(attributes)
+        raise draft_exception unless version.draft?
+
+        with_transaction_returning_status do
+          assign_attributes(attributes)
+          save
+        end
+      end
+      alias update_attributes update
+
+      def update!(attributes)
+        raise draft_exception unless version.draft?
+
+        with_transaction_returning_status do
+          assign_attributes(attributes)
+          save!
+        end
+      end
+      alias update_attributes! update!
+
+      def live?
+        false
+      end
+
+      def version?
+        true
+      end
+
+      def commit(params = {})
+        raise draft_exception unless version.draft?
+
+        attrs = version_attributes.tap do |attrs|
+          attrs.merge!(
+            draft:        false,
+            event:        ActiveVersioning::Events::COMMIT,
+            committed_at: Time.current
+          )
+
+          attrs.merge!(params)
+        end
+
+        version.update(attrs)
+
+        __getobj__.update(versioned_attributes)
+      end
+
+      private
+
+      def draft_exception
+        ActiveVersioning::Errors::InvalidVersion.new("Version #{version.id} must be a draft")
+      end
+
+      def version_attributes
+        {
+          committer: version_author,
+          object:    versioned_attributes
+        }
+      end
+    end
+  end
+end

data/lib/active_versioning/model/versioned.rb

@@ -0,0 +1,73 @@
+module ActiveVersioning
+  module Model
+    module Versioned
+      def self.included(base)
+        base.class_eval do
+          has_many :versions, -> { newest_first }, as: :versionable, dependent: :destroy
+
+          after_create :create_version!
+
+          attr_accessor :version_author
+        end
+      end
+
+      def live?
+        true
+      end
+
+      def version?
+        false
+      end
+
+      def current_draft(force_reload = false)
+        unless persisted?
+          raise ActiveVersioning::Errors::RecordNotPersisted.new("#{self} must be persisted to create a draft version")
+        end
+
+        @current_draft = nil if force_reload
+
+        @current_draft ||= VersionProxy.new(versions.draft.first_or_create(
+          object: versioned_attributes,
+          event:  'draft'
+        ))
+      end
+
+      def current_draft?
+        versions.draft.present?
+      end
+
+      def destroy_draft
+        versions.draft.destroy_all
+      end
+
+      def version_manager
+        @version_manager ||= VersionManager.new(self)
+      end
+
+      def create_draft_from_version(version_id)
+        version_manager.create_draft_from_version(version_id) and current_draft(true)
+      end
+
+      def versioned_attributes
+        versioned_attribute_names.reduce(Hash.new) do |attrs, name|
+          attrs.merge(name => send(name))
+        end
+      end
+
+      def versioned_attribute_names
+        attribute_names - VersionManager::BLACKLISTED_ATTRIBUTES
+      end
+
+      private
+
+      def create_version!
+        versions.create!(
+          event:        ActiveVersioning::Events::CREATE,
+          committer:    version_author,
+          committed_at: Time.current,
+          object:       versioned_attributes
+        )
+      end
+    end
+  end
+end

data/lib/active_versioning/model.rb

@@ -0,0 +1,37 @@
+module ActiveVersioning
+  module Model
+    extend ActiveSupport::Concern
+
+    autoload :Versioned,    'active_versioning/model/versioned'
+    autoload :VersionProxy, 'active_versioning/model/version_proxy'
+
+    included do
+      belongs_to :versionable, polymorphic: true
+
+      serialize :object, Hash
+
+      validates :event, presence: true, inclusion: { in: ActiveVersioning::Events::ALL }
+
+      scope :newest_first, -> { order created_at: :desc }
+      scope :draft,        -> { where draft: true }
+      scope :committed,    -> { where draft: false }
+
+      def to_s
+        [
+          versionable.to_s,
+          committed_at.try(:utc).try(:strftime, '#%Y%m%d%H%M%S')
+        ].compact.join(' ')
+      end
+
+      def reify
+        resource = versionable(true)
+
+        # Necessary to ensure resource and versionable are two distinct objects in memory
+        versionable(true)
+
+        resource.assign_attributes(object.slice(*resource.versioned_attribute_names))
+        resource
+      end
+    end
+  end
+end

data/lib/active_versioning/version.rb

@@ -0,0 +1,3 @@
+module ActiveVersioning
+  VERSION = "0.1.0"
+end

data/lib/active_versioning/version_manager.rb

@@ -0,0 +1,31 @@
+module ActiveVersioning
+  class VersionManager < Struct.new(:record)
+    BLACKLISTED_ATTRIBUTES = %w(
+      created_at
+      updated_at
+      published
+    )
+
+    def create_draft_from_version(id)
+      version = record.versions.find(id)
+
+      ensure_compatibility_with(version)
+
+      new_version        = record.versions.draft.first_or_create(event: 'draft')
+      new_version.object = version.object
+      new_version.save
+    end
+
+    def ensure_compatibility_with(version)
+      incompatible_attributes(version).tap do |incompatible_attrs|
+        if incompatible_attrs.any?
+          raise Errors::IncompatibleVersion.new(record, version), "The given version contains attributes that are no longer compatible with the current schema: #{incompatible_attrs.to_sentence}."
+        end
+      end
+    end
+
+    def incompatible_attributes(version)
+      version.object.keys - record.attributes.keys
+    end
+  end
+end

data/lib/active_versioning.rb

@@ -0,0 +1,9 @@
+require 'active_versioning/version'
+require 'generators/active_versioning_generator'
+
+module ActiveVersioning
+  autoload :Errors,         'active_versioning/errors'
+  autoload :Events,         'active_versioning/events'
+  autoload :Model,          'active_versioning/model'
+  autoload :VersionManager, 'active_versioning/version_manager'
+end

data/lib/generators/active_versioning_generator.rb

@@ -0,0 +1,15 @@
+require 'rails/generators/active_record/migration'
+
+class ActiveVersioningGenerator < Rails::Generators::Base
+  include ActiveRecord::Generators::Migration
+
+  source_root File.expand_path('../templates', __FILE__)
+
+  def install_models
+    copy_file 'models/version.rb', 'app/models/version.rb'
+  end
+
+  def install_migrations
+    migration_template 'migrations/create_versions.rb', 'db/migrate/create_versions.rb'
+  end
+end

data/lib/generators/templates/migrations/create_versions.rb

@@ -0,0 +1,18 @@
+class CreateVersions < ActiveRecord::Migration
+  def change
+    create_table :versions do |t|
+      t.string   :versionable_type, null: false
+      t.integer  :versionable_id,   null: false
+      t.string   :event,            null: false
+      t.string   :committer
+      t.text     :object
+      t.boolean  :draft,            default: false
+      t.text     :commit_message
+      t.datetime :committed_at
+
+      t.timestamps null: false
+    end
+
+    add_index :versions, [:versionable_type, :versionable_id]
+  end
+end

data/lib/generators/templates/models/version.rb

@@ -0,0 +1,3 @@
+class Version < ActiveRecord::Base
+  include ActiveVersioning::Model
+end

metadata

@@ -0,0 +1,207 @@
+--- !ruby/object:Gem::Specification
+name: active_versioning
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ryan Stenberg
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-09-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.1
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: shoulda-matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: generator_spec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: codeclimate-test-reporter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ActiveVersioning serializes attributes when records are saved and allows
+  for version and draft management.
+email:
+- ryan.stenberg@viget.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- active_versioning.gemspec
+- bin/console
+- bin/setup
+- circle.yml
+- lib/active_versioning.rb
+- lib/active_versioning/errors.rb
+- lib/active_versioning/errors/incompatible_version.rb
+- lib/active_versioning/events.rb
+- lib/active_versioning/model.rb
+- lib/active_versioning/model/version_proxy.rb
+- lib/active_versioning/model/versioned.rb
+- lib/active_versioning/version.rb
+- lib/active_versioning/version_manager.rb
+- lib/generators/active_versioning_generator.rb
+- lib/generators/templates/migrations/create_versions.rb
+- lib/generators/templates/models/version.rb
+homepage: https://github.com/vigetlabs/active_versioning
+licenses:
+- BSD
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Plug-and-Play Versioning for Rails
+test_files: []