secretary-rails 1.0.0.beta1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 Bryan Ricker, SCPR
+
+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.md

@@ -0,0 +1,186 @@
+# Secretary
+
+#### A note about the Gem name
+There is another gem called [`secretary`](http://rubygems.org/gems/secretary),
+which hasn't been updated since 2008 and is obsolete. This gem is called
+`secretary-rails` since `secretary` is already taken on RubyGems. However, the
+module name is the same, so using them together would be difficult.
+
+
+### What is it?
+Light-weight model versioning for ActiveRecord 3.2+.
+
+### How does it work?
+Whenever you save your model, a new version is saved. The changes are
+serialized and stored in the database, along with a version description,
+foreign keys to the object, and a foreign key to the user who saved the object.
+
+### Why is it better than [other versioning gem]?
+* It tracks associations.
+* It provides diffs (using the [`diffy`](http://rubygems.org/gems/diffy) gem).
+* It only stores the changes, not the whole object.
+* It is simple.
+
+### Compatibility
+* Rails 3.2+
+* SQLite
+* MySQL? (untested)
+* Postgres? (untested)
+
+### Dependencies
+* [`activerecord`](http://rubygems.org/gems/activerecord) >= 3.2.0
+* [`railties`](http://rubygems.org/gems/railties) >= 3.2.0
+* [`diffy`](http://rubygems.org/gems/diffy) ~> 3.0.1
+
+
+## Installation
+Add to your gemfile:
+
+```ruby
+gem 'secretary-rails'
+```
+
+Run the install command, which will create a migration to add the `versions`
+table, and then run it:
+
+```
+bundle exec rails generate secretary:install
+bundle exec rake db:migrate
+```
+
+
+## Usage
+Add the `has_secretary` macro to your model:
+
+```ruby
+class Article < ActiveRecord::Base
+  has_secretary
+end
+```
+
+Congratulations, now your records are being versioned.
+
+### Tracking associations
+This gem is built with the end-user in mind, so it doesn't track hidden
+associations (i.e. join models). However, you can tell it to track associated
+objects WITHIN their parent object's version by using the `tracks_association`
+macro. For example:
+
+```ruby
+class Author < ActiveRecord::Base
+  has_many :article_authors
+  has_many :articles, through: :article_authors
+end
+
+class ArticleAuthor < ActiveRecord::Base
+  belongs_to :article
+  belongs_to :author
+end
+
+class Article < ActiveRecord::Base
+  has_secretary
+
+  has_many :article_authors
+  has_many :authors, through: :article_authors
+  tracks_association :authors
+end
+```
+
+Now, when you save an `Article`, a new version won't be created for the
+new `ArticleAuthor` object(s). Instead, an array will be added to the `Article`'s
+changes, which will include the information about the author(s).
+
+You can also pass in multiple association names into `tracks_association`.
+
+### Tracking Users
+A version has an association to a user object, which tells you who created that
+version. The logged user is an attribute on the object being changed, so you
+can add it in via the controller:
+
+```ruby
+class ArticlesController < ApplicationControler
+  before_filter :get_object, only: [:show, :edit, :update, :destroy]
+  before_filter :inject_logged_user, only: [:update]
+
+  def create
+    @article = Article.new(article_params)
+    inject_logged_user
+    # ...
+  end
+
+  # ...
+
+  private
+
+  def get_object
+    @article = Article.find(params[:id])
+  end
+
+  def inject_logged_user
+    @article.logged_user_id = @current_user.id
+  end
+end
+```
+
+### Configuration
+In an initializer (may we suggest `secretary.rb`?), add:
+
+```ruby
+# This is a list of all the possible configurations and their defaults.
+Secretary.configure do |config|
+  config.user_class         = "::User"
+  config.ignored_attributes = ["id", "created_at", "updated_at"]
+end
+```
+
+* **user_class** - The class for your user model.
+* **ignored_attributes** - The attributes which should always be ignored
+  when generating a version, for every model, as an array of Strings.
+
+### Specifying which attributes to keep track of
+Sometimes you have an attribute on your model that either isn't public
+(not in the form), or you just don't want to version. You can tell Secretary
+to ignore these attributes globally by setting
+`Secretary.config.ignore_attributes`. You can also ignore attributes on a
+per-model basis by using one of two methods:
+
+```ruby
+class Article < ActiveRecord::Base
+  has_secretary
+
+  # Included
+  self.versioned_attributes = ["headline", "body"]
+end
+```
+
+```ruby
+class Article < ActiveRecord::Base
+  has_secretary
+
+  # Excluded
+  self.unversioned_attributes = ["published_at", "is_editable"]
+end
+```
+
+By default, `versioned_attributes` is the model's column names, minus the
+globally configured `ignored_attributes`, minus any `unversioned_attributes`
+you have set. `tracks_association` adds those associations to the
+`versioned_attributes` array.
+
+
+## Contributing
+Fork it and send a pull request!
+
+### TODO
+* Rails 4.1+ support.
+* Test (officially) with MySQL and SQLite.
+* Associations are only tracked one-level deep, It would be nice to also
+  track the changes of the association (i.e. recognize when an associated
+  object was changed and show its changed, instead of just showing a whole
+  new object).
+* Support for Rails 3.0 and 3.1.
+
+### Running Tests
+This library uses [appraisal](https://github.com/thoughtbot/appraisal) to test
+against different Rails versions. To run the test suite on all versions, use
+`appraisal rspec`.

data/Rakefile

@@ -0,0 +1,9 @@
+#!/usr/bin/env rake
+require 'bundler/setup'
+require 'appraisal'
+require 'rspec/core/rake_task'
+
+Bundler::GemHelper.install_tasks
+
+RSpec::Core::RakeTask.new(:test)
+task :default => :test

data/app/models/secretary/version.rb

@@ -0,0 +1,93 @@
+module Secretary
+  class Version < ActiveRecord::Base
+    serialize :object_changes
+
+    belongs_to :versioned, polymorphic: true
+    belongs_to :user, class_name: Secretary.config.user_class
+
+    validates_presence_of :versioned
+
+    before_create :increment_version_number
+
+
+    class << self
+      # Builds a new version for the passed-in object
+      # Passed-in object is a dirty object.
+      # Version will be saved when the object is saved.
+      #
+      # If you must generate a version manually, this
+      # method should be used instead of `Version.create`.
+      # I didn't want to override the public ActiveRecord
+      # API.
+      def generate(object)
+        object.versions.create({
+          :user_id          => object.logged_user_id,
+          :description      => generate_description(object),
+          :object_changes   => object.versioned_changes
+        })
+      end
+
+
+      private
+
+      def generate_description(object)
+        if was_created?(object)
+          "Created #{object.class.name.titleize} ##{object.id}"
+
+        elsif was_updated?(object)
+          attributes = object.versioned_changes.keys
+          "Changed #{attributes.to_sentence}"
+
+        else
+          "Generated Version"
+        end
+      end
+
+
+      def was_created?(object)
+        object.persisted? && object.id_changed?
+      end
+
+      def was_updated?(object)
+        object.persisted? && !object.id_changed?
+      end
+    end
+
+
+    # The attribute diffs for this version
+    def attribute_diffs
+      @attribute_diffs ||= begin
+        changes           = self.object_changes.dup
+        attribute_diffs   = {}
+
+        # Compare each of object_b's attributes to object_a's attributes
+        # And if there is a difference, add it to the Diff
+        changes.each do |attribute, values|
+          # values is [previous_value, new_value]
+          diff = Diffy::Diff.new(values[0].to_s, values[1].to_s)
+
+          if diff.string1 != diff.string2
+            attribute_diffs[attribute] = diff
+          end
+        end
+
+        attribute_diffs
+      end
+    end
+
+    # A simple title for this version.
+    # Example: "Article #125 v6"
+    def title
+      "#{self.versioned.class.name.titleize} " \
+      "##{self.versioned.id} v#{self.version_number}"
+    end
+
+
+    private
+
+    def increment_version_number
+      latest_version = self.versioned.versions.order("version_number").last
+      self.version_number = latest_version.try(:version_number).to_i + 1
+    end
+  end
+end

data/lib/generators/secretary/install_generator.rb

@@ -0,0 +1,23 @@
+require 'rails/generators'
+
+module Secretary
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    if ActiveRecord::VERSION::MAJOR < 4
+      require 'rails/generators/active_record/migration'
+      extend ActiveRecord::Generators::Migration
+    else
+      require 'rails/generators/active_record'
+      def self.next_migration_number(*args)
+        ActiveRecord::Generators::Base.next_migration_number(*args)
+      end
+    end
+
+    source_root File.expand_path("../templates", __FILE__)
+
+    def copy_migration
+      migration_template "versions_migration.rb", "db/migrate/create_versions"
+    end
+  end
+end

data/lib/generators/secretary/templates/versions_migration.rb

@@ -0,0 +1,18 @@
+class SecretaryCreateVersions < ActiveRecord::Migration
+  def change
+    create_table "versions" do |t|
+      t.integer  "version_number"
+      t.string   "versioned_type"
+      t.integer  "versioned_id"
+      t.string   "user_id"
+      t.text     "description"
+      t.text     "object_changes"
+      t.datetime "created_at"
+    end
+
+    add_index "versions", ["created_at"]
+    add_index "versions", ["user_id"]
+    add_index "versions", ["version_number"]
+    add_index "versions", ["versioned_type", "versioned_id"]
+  end
+end

data/lib/secretary/config.rb

@@ -0,0 +1,19 @@
+module Secretary
+  class Config
+    DEFAULTS = {
+      :user_class           => "::User",
+      :ignored_attributes   => ['id', 'created_at', 'updated_at']
+    }
+
+
+    attr_writer :user_class
+    def user_class
+      @user_class || DEFAULTS[:user_class]
+    end
+
+    attr_writer :ignored_attributes
+    def ignored_attributes
+      @ignored_attributes || DEFAULTS[:ignored_attributes]
+    end
+  end
+end

data/lib/secretary/engine.rb

@@ -0,0 +1,4 @@
+module Secretary
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/secretary/errors.rb

@@ -0,0 +1,10 @@
+class Secretary::NotVersionedError < StandardError
+  def initialize(klasses=nil)
+    @klasses = Array(klasses)
+  end
+
+  def message
+    "Can't track an association on an unversioned model " \
+    "(#{@klasses.join(", ")}) Did you declare `has_secretary` first?"
+  end
+end

data/lib/secretary/gem_version.rb

@@ -0,0 +1,3 @@
+module Secretary
+  GEM_VERSION = "1.0.0.beta1"
+end

data/lib/secretary/has_secretary.rb

@@ -0,0 +1,75 @@
+module Secretary
+  module HasSecretary
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Check if a class is versioned
+      def has_secretary?
+        !!@_has_secretary
+      end
+
+      # Apply to any class that should be versioned
+      def has_secretary
+        @_has_secretary = true
+        Secretary.versioned_models.push self.name
+
+        has_many :versions,
+          :class_name   => "Secretary::Version",
+          :as           => :versioned,
+          :dependent    => :destroy
+
+        attr_accessor :logged_user_id
+
+        after_save    :generate_version, if: -> { self.changed? }
+        after_commit  :clear_custom_changes
+
+        send :include, InstanceMethodsOnActivation
+      end
+    end
+
+
+    module InstanceMethodsOnActivation
+      # Generate a version for this object.
+      def generate_version
+        Version.generate(self)
+      end
+
+      # Use Rails built-in Dirty attributions to get
+      # the easy ones. By the time we're generating
+      # this version, this hash could already
+      # exist with some custom changes.
+      def changes
+        self.custom_changes.reverse_merge super
+      end
+
+      # Use Rails' `changed?`, plus check our own custom changes
+      # to see if an object has been modified.
+      def changed?
+        super || custom_changes.present?
+      end
+
+      # Similar to ActiveModel::Dirty#changes, but lets us
+      # pass in some custom changes (such as associations)
+      # which wouldn't be picked up by the built-in method.
+      #
+      # This method should only be used for adding custom changes
+      # to the changes hash. For storing and comparing and whatnot,
+      # use #changes as usual.
+      #
+      # This method basically exists just to get around the behavior
+      # of #changes (since it sends the attribute message to the
+      # object, which we don't always want, for associations for
+      # example).
+      def custom_changes
+        @custom_changes ||= HashWithIndifferentAccess.new
+      end
+
+
+      private
+
+      def clear_custom_changes
+        self.custom_changes.clear
+      end
+    end
+  end
+end

data/lib/secretary/tracks_association.rb

@@ -0,0 +1,146 @@
+module Secretary
+  module TracksAssociation
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Track the associations passed-in
+      # This will make sure that when you change the association,
+      # the saved record will get a new version, with association
+      # diffs and everything.
+      #
+      # Example:
+      #
+      #   has_secretary
+      #
+      #   has_many :bylines,
+      #     :as               => :content,
+      #     :class_name       => "ContentByline",
+      #     :dependent        => :destroy
+      #
+      #   tracks_association :bylines
+      #
+      # Forcing the changes into the custom_changes allows us
+      # to keep track of dirty associations, so that checking stuff
+      # like `changed?` will work.
+      # 
+      # If you want to control when an association should be left out of the
+      # version, define an instance method named `should_reject_#{name}?`.
+      # This method takes a hash of the model's attributes (so you can pass
+      # in, for example, form params). This also lets you easily share this
+      # method with `accepts_nested_attributes_for`.
+      #
+      # Example:
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_secretary
+      #     has_many :animals
+      #     tracks_association :animals
+      #
+      #     accepts_nested_attributes_for :animals,
+      #       :reject_if => :should_reject_animals?
+      #
+      #     private
+      #
+      #     def should_reject_animals?(attributes)
+      #       attributes['name'].blank?
+      #     end
+      #   end
+      def tracks_association(*associations)
+        if !self.has_secretary?
+          raise NotVersionedError, self.name
+        end
+
+        self.versioned_attributes += associations.map(&:to_s)
+
+        include InstanceMethodsOnActivation
+
+        associations.each do |name|
+          module_eval <<-EOE, __FILE__, __LINE__ + 1
+            def #{name}_were
+              @#{name}_were ||= association_was("#{name}")
+            end
+
+            def #{name}_changed?
+              association_changed?("#{name}")
+            end
+
+
+            private
+
+            def preload_#{name}_were(object)
+              #{name}_were
+            end
+
+            def check_for_#{name}_changes
+              check_for_association_changes("#{name}")
+            end
+
+            def clear_dirty_#{name}
+              @#{name}_were = nil
+            end
+          EOE
+
+          before_save :"check_for_#{name}_changes"
+          after_commit :"clear_dirty_#{name}"
+
+          add_callback_methods("before_add_for_#{name}", [
+            :"preload_#{name}_were"
+          ])
+
+          add_callback_methods("before_remove_for_#{name}", [
+            :"preload_#{name}_were"
+          ])
+
+          add_callback_methods("after_add_for_#{name}", [])
+          add_callback_methods("after_remove_for_#{name}", [])
+        end
+      end
+
+      private
+
+      def add_callback_methods(method_name, new_methods)
+        original  = send(method_name)
+        methods   = original + new_methods
+        send("#{method_name}=", methods)
+      end
+    end
+
+
+    module InstanceMethodsOnActivation
+      private
+
+      # This has to be run in a before_save callback,
+      # because we can't rely on the after_add, etc. callbacks
+      # to fill in our custom changes. For example, setting
+      # `self.animals_attributes=` doesn't run these callbacks.
+      def check_for_association_changes(name)
+        persisted   = self.send("#{name}_were")
+        current     = self.send(name).to_a.reject(&:marked_for_destruction?)
+
+        persisted_attributes  = persisted.map(&:versioned_attributes)
+        current_attributes    = current.map(&:versioned_attributes)
+
+        if persisted_attributes != current_attributes
+          ensure_custom_changes_for_association(name, persisted)
+          self.custom_changes[name][1] = current_attributes
+        end
+      end
+
+      def association_was(name)
+        self.persisted? ? self.class.find(self.id).send(name).to_a : []
+      end
+
+      def association_changed?(name)
+        check_for_association_changes(name)
+        self.custom_changes[name].present?
+      end
+
+      def ensure_custom_changes_for_association(name, persisted=nil)
+        self.custom_changes[name] ||= [
+          (persisted || self.send("#{name}_were")).map(&:versioned_attributes),
+          Array.new
+        ]
+      end
+    end
+  end
+end

data/lib/secretary/versioned_attributes.rb

@@ -0,0 +1,58 @@
+module Secretary
+  module VersionedAttributes
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        # Set the attributes which Secretary should keep track of.
+        #
+        # Example:
+        #
+        #   class Article < ActiveRecord::Base
+        #     self.versioned_attributes = [:id, :created_at]
+        #   end
+        #
+        # Instead of setting `versioned_attributes` explicitly,
+        # you can set `unversioned_attributes` to tell Secretary
+        # which attributes to ignore.
+        #
+        # Note: These should be set before any `tracks_association`
+        # macros are called.
+        #
+        # Each takes an array of column names *as strings*.
+        attr_writer :versioned_attributes
+
+        def versioned_attributes
+          @versioned_attributes ||=
+            self.column_names -
+            Secretary.config.ignored_attributes -
+            unversioned_attributes
+        end
+
+        def unversioned_attributes=(array)
+          self.versioned_attributes -= array
+        end
+
+        private
+
+        def unversioned_attributes
+          @unversioned_attributes ||= []
+        end
+      end
+    end
+
+
+    # The hash that gets serialized into the `object_changes` column.
+    def versioned_changes
+      self.changes.select { |k,_| versioned_attribute?(k) }.to_hash
+    end
+
+    def versioned_attributes
+      self.as_json(root: false).select { |k,_| versioned_attribute?(k) }.to_hash
+    end
+
+    def versioned_attribute?(key)
+      self.class.versioned_attributes.include?(key.to_s)
+    end
+  end
+end

data/lib/secretary-rails.rb

@@ -0,0 +1,3 @@
+# This file is nothing.
+# It's here to trick rubygems. >:D
+require 'secretary'