draft_punk 0.2.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 736d197cd13d789cca1213de1254c89a1082fddc
-  data.tar.gz: faa8ed97c0233efc97494180dfdfa4c26cfec3ee
+  metadata.gz: 904244863752dbaa1f78496c19b136af59d1dba5
+  data.tar.gz: 8c4e60640cd7728e6988253af6cdbf0bfc5d86d4
 SHA512:
-  metadata.gz: 1b1f61d8ad5f526b41f406c5aeb6e410f5eda164fa1d55efc356695b7af42314c6d43984ff877b6693429e9562587c47dc2b9e75de975bd0308b0bd2a052c902
-  data.tar.gz: c21fb1a305501bb941e8ba2cdce4da2dbb4efea82e32fe82f959746c16340c0b90d874e137f2a0deffd1fa14e544bcc26eda3928910e6fdaf55bf588a8e542a6
+  metadata.gz: 02d77960c5c1771d34b2d2b17bb32d1061e9d53ae8223c64b8df0286814bb3056d24e50a93ef37c51b439be10fed8b79090b6c491d0a822deae18783e618ae8f
+  data.tar.gz: d7844a4ccdc4e2cfe552499e913d25a805d9bbadfcbdc14974a703fa0d72d13ee34aff01ef93538ea2308f50610eeb0a55b6f424b005ba2d13363a57886c3cd5

data/Appraisals

@@ -0,0 +1,11 @@
+appraise "rails-5-0" do
+  gem "rails", "~> 5.0.0"
+end
+
+appraise "rails-5-1" do
+  gem "rails", "~> 5.1.0"
+end
+
+appraise "rails-5-2" do
+  gem "rails", "~> 5.2.0"
+end

data/README.md

@@ -6,28 +6,29 @@ When it's time to edit, a draft version is created in the same table as the obje
 
 When it's time to publish, any attributes changed on your draft object persist to the original object. All associated objects behave the same way. Any associated have_many objects which are deleted on the draft are deleted on the original object.
 
-## Why this gem compared to similar gems?
-
-I wrote this gem because other draft/publish gems had limitations that ruled them out in my use case. Here's a few reasons I ended up rolling my own:
-
-1. This gem simply works with your existing database (plus one new column on your original object).
-2. I tried using an approach that stores incremental changes in another table. For instance, some draft gems rely on a Versioning gem, or otherwise store incremental changes in the database.
-
-    That gets super complicated, or simply don't work, with associations, nested associations, and/or if you want users to be able to *edit* those changes.
-3. This gem works with Rails `accepts_nested_attributes`. That Rails pattern doesn't work when you pass in objects which aren't associated; for instance, if you try to save a new draft image on your Blog post via nested_attributes, Rails will throw a 404 error. It got nasty, fast, so I needed a solution that worked well with Rails.
-4. I prefer to store drafts in the same table as the original. While this has a downside (see downsides, below), it means:
-    1. Your draft acts like the original. You can execute all the same methods on it, reuse presenters, forms, form_objects, decorators, or anything else. It doesn't just quack like a duck, it **is** a duck.
-
-    2. This prevents your table structure from getting out of sync. If you're using DraftPunk, when you add a new attribute to your model, or change a column, both your live/approved version and your draft version are affected. Using a different pattern, if they live in separate tables, you may need to run migrations on both tables (or, migrate the internals of a version diff if your draft gem relies on something like Paper Trail or VestalVersion)
-  
-
-### Downsides
-
-Since DraftPunk saves in the same table as the original, your queries in those tables will return both approved and draft objects. In other words, without modifying your Rails app further, your BusinessController index action (in a typical rails app) will return drafts and approved objects. DraftPunk adds scopes to help you manage this. See the "What about the rest of the application? People are seeing draft businesses!" section below for two patterns to address this. 
+* [Usage](#usage)
+  * [Enable Draft Creation](#enable-draft-creation)
+  * [Association Drafts](#association-drafts) - including customization of which associations use drafts
+  * [Updating a draft](#updating-a-draft) - including controllers and forms
+  * [Publish a draft](#publish-a-draft) - including controllers and forms
+  * [Tracking drafts](#tracking-drafts) - methods to tell you if the object is a draft or is approved
+* [What about the rest of the application? People are seeing draft businesses!](#what-about-the-rest-of-the-application-people-are-seeing-draft-businesses)
+* Options
+  * [When creating a draft](#when-creating-a-draft)
+    * [Handling attributes with uniqueness validations](#handling-attributes-with-uniqueness-validations)
+    * [Before create draft callback](#before-create-draft-callback)
+    * [After create draft callback](#after-create-draft-callback)
+  * [When publishing a draft](#when-publishing-a-draft)
+    * [Before publish draft callback](#before-publish-draft-callback)
+    * [Customize which attributes are published](#customize-which-attributes-are-published)
+  * [Storing approved version history](#storing-approved-version-history)
+    * [Prevent historic versions from being saved](#prevent-historic-versions-from-being-saved)
+* [Installation](#installation)
+* [Testing the gem](#testing-the-gem)
 
 ## Usage
 
-### Getting Started
+### Enable Draft Creation
 To enable drafts for a model, first add an approved_version_id column (Integer), which will be used to track its draft.
 
 Simply call requires_approval in your model to enable DraftPunk on that model and its associations:
@@ -41,29 +42,27 @@ Simply call requires_approval in your model to enable DraftPunk on that model an
       requires_approval 
     end
 
-DraftPunk will generate drafts for all associations, by default. So when you create a draft Business, that draft will also have draft `employees`, `vending_machines`, `images`, and an `address`. The whole tree is recursively duplicated.
-
-**Do not call `requires_approval` on Business's associated objects.** The behavior automatically cascades down til there are no more associations.
+### Association Drafts
+**DraftPunk will generate drafts for all associations**, by default. So when you create a draft Business, that draft will also have draft `employees`, `vending_machines`, `images`, and an `address`. **The whole tree is recursively duplicated.**
 
-### Customize which associations have drafts created
+**Do not call `requires_approval` on Business's associated objects.** The behavior automatically cascades down until there are no more associations.
 
 Optionally, you can tell DraftPunk which associations the user will edit - the associations which should have a draft created.
 
-If you only want the :address association to have a draft created, add a CREATES_NESTED_DRAFTS_FOR constant in your model:
+If you only want the :address association to have a draft created, add a `CREATES_NESTED_DRAFTS_FOR` constant in your model:
 
     CREATES_NESTED_DRAFTS_FOR = [:address] # When creating a business's draft, only :address will have drafts created
 
-To disable drafts for all assocations for this model, simply pass an empty array:
+To disable drafts for all associations for this model, simply pass an empty array:
 
     CREATES_NESTED_DRAFTS_FOR = [] # When creating a business's draft, no associations will have drafts created
 
-**WARNING: If you are setting associations via accepts_nested_attributes** _all changes to the draft, including associations, get set on the
-draft object (as expected). If your form includes associated objects which weren't defined in requires_approval, your save will fail since
+**WARNING: If you are setting associations via `accepts_nested_attributes`** _all changes to the draft, including associations, get set on the
+draft object (as expected). If your form includes associated objects which weren't defined in `requires_approval`, your save will fail since
 the draft object doesn't HAVE those associations to update! In this case, you should probably add that association to the
 `associations` param when you call `requires_approval`._
 
-
-### Working with a draft
+### Updating a draft
 
 So you have an ActiveRecord object:
 
@@ -93,32 +92,34 @@ Your update action might look like so:
       .... do some stuff here
     end
 
-So your draft is automagically getting updated.
+So your draft is automatically getting updated.
 
-Say your `@business` has a `name` attribute:
+If your `@business` has a `name` attribute:
 
     @business.name
     => "DraftPunk LLC"
 
-Ok, you just incorperated so your name changed.
+And you change your name:
 
     @my_draft = @business.editable_version
-    @my_draft.name = "DraftPunk Incorperated"
+    @my_draft.name = "DraftPunk Inc"
     @my_draft.save
 
 At this point, that change is only saved on the draft version of your business. The original business still has the name DraftPunk LLC.
 
-#### Publish the draft - aka making your changes live
+### Publish a draft
+
+Publishing the draft publishes the draft object's changes onto the approved version. The draft is then destroyed. Example:
 
 So you want to make your changes live:
 
     @business.name
     => "DraftPunk LLC"
     @business.draft.name
-    => "DraftPunk Incorperated"    
+    => "DraftPunk Inc"    
     @business.publish_draft!
     @business.name
-    => "DraftPunk Incorperated"    
+    => "DraftPunk Inc"    
 
 **All of the @business associations copied from the draft**. More correctly, the foreign_keys on has_many associations are changed, set to the original object (@business) id. All the old associations (specified in requires_approval) on @business are destroyed.
 
@@ -128,7 +129,7 @@ At this point, the draft is destroyed. Next time you call `editable_version`, a
 Your original model has a few methods available:
 
     @business.id
-    => 1    
+    => 1
     @draft = @business.draft
     => Business(id: 2, ...)
     @draft.approved_version
@@ -149,7 +150,7 @@ Your associations can have this behavior, too, which could be useful in your app
     @draft_image = @business.draft.images.first
     => Image(id: 2, ...)
 
-At this point, if you don't have `approved_version_id` on the `images` table, there's no way for you to know that @draft_image was originally a copy of @live_image. If you have approved_version_id on your table, you can call:
+At this point, if you don't have `approved_version_id` on the `images` table, there's no way for you to know that `@draft_image` was originally a copy of `@live_image`. If you have `approved_version_id` on your table, you can call:
 
     @draft_image.approved_version
     => Image(id: 1, ...)
@@ -158,23 +159,23 @@ At this point, if you don't have `approved_version_id` on the `images` table, th
 
 You now know for certain that the two are associated, which could be useful in your app.
 
-### Free ActiveRecord scopes
+### ActiveRecord scopes
 All models which have `approved_version_id` also have these scopes: `approved` and `draft`.
 
 ## What about the rest of the application? People are seeing draft businesses!
 
 You can implement this in a variety of ways. Here's two approaches:
 
-#### Set a Rails `default_scope` on your model.
+### Set a Rails `default_scope` on your model.
 
-This is the quickest, most DRY way to address this, but of course default_scopes aren't always the right answer for every Rails app.
+This is the quickest, most DRY way to address this:
 
     default_scope Business.approved
 
-Then, any ActiveRecord queries for Business will be scoped to only approved models. Your `draft` scope, and `draft` association will ignore this scope, so @business.draft and Business.draft will both continue to return draft objects. 
+Then, any ActiveRecord queries for Business will be scoped to only approved models. Your `draft` scope, and `draft` association will ignore this scope, so `@business.draft` and `Business.draft` will both continue to return draft objects. 
 
 
-#### Or, modify your controllers to use the `approved` scope
+### Or, modify your controllers to use the `approved` scope
 Alternately, you may want to modify your controllers to only access _approved_ objects. For instance, your business controller should use that `approved` scope when it looks up businesses. i.e.
 
     class BusinessesController < ApplicationController
@@ -184,19 +185,11 @@ Alternately, you may want to modify your controllers to only access _approved_ o
       end
     end
 
-## TODO: Customizing Association associations (grandchildren) using accepts_nested_drafts_for
-
-## TODO: Customizing approvable_attributes, changes_require_approval
+## Options
 
-## Options before creating a draft
+### When creating a draft
 
-When calling `requires_approval`, you can pass a `nullify` option to set attributes to null once the draft is created:
-
-    requires_approval nullify: [:subdomain]
-
-This could be useful if your model has an attribute which should not persist. In this example, each Business has a unique subdomain (ie. business_name.foo.com ). By nullifying this out, the subdomain on the draft would be nil. 
-
-### Before create callback
+#### Before create draft callback
 
 If you define a method on your model called `before_create_draft`, that method will be executed before the draft is created.
 
@@ -206,20 +199,80 @@ You can access `self` (which is the DRAFT version being created), or the `tempor
       logger.warn "#{self.name} is being created from #{temporary_approved_object.class.name} ##{temporary_approved_object.id}" # outputs: DerpCorp is being created from Business #1
     end
 
-### After create callback
+#### After create draft callback
 
 If you define a method on your model called `after_create_draft`, that method will be executed before the draft is created. This is useful in cases when you need a fully set-up draft to modify. For instance, after all of its associations have been set.
 
 You can access `self` (which is the DRAFT version being created), or the `temporary_approved_object` (the original object) in this method
 
-**Note that you are responsible for any saves needed**. draft_punk does not save again after your after_create executes
+**Note that you are responsible for any saves needed**. `draft_punk` does not save again after your after_create executes
 
-## Options before publishing a draft
+#### Handling attributes with uniqueness validations
+When calling `requires_approval`, you can pass a `nullify` option to set attributes to null once the draft is created:
+
+    requires_approval nullify: [:subdomain]
+
+This could be useful if your model has an attribute which should not persist. In this example, each Business has a unique subdomain (ie. business_name.foo.com ). By nullifying this out, the subdomain on the draft would be nil. 
 
-### Before publish draft method
+### When publishing a draft
+
+#### Before publish draft callback
 
 If you define a method on your model called `before_publish_draft`, that method will be executed before the draft is published. Specifically, it happens after all attributes are copied from the draft to the approved version, and right before the approved version is saved. This allows you to do whatever you'd like to the model before it is saved.
 
+#### Customize which attributes are published
+
+When a draft is published, most attributes are copied from the draft to the approved version. Naturally, created-at and id would not be copied.
+
+You can control the whitelist of attributes to copy by defining `approvable_attributes` method in each model where you need custom behavior.
+
+For instance, if each object has a unique `token` attributes, you may not want to copy that to the approved version upon publishing:
+
+    def approvable_attributes
+      self.attributes.keys - ["token"]
+    end
+
+    @business.token
+    => '12345'
+    @business.draft.token
+    => 'abcde'
+    @business.publish_draft!
+    @business.token
+    => '12345' # it was not changed
+
+### TODO: Customizing Association associations (grandchildren) using accepts_nested_drafts_for
+### TODO: Customizing changes_require_approval
+
+### Storing approved version history
+
+You can optionally store the history of approved versions of an object. For instance:
+
+    @business.name
+    => "DraftPunk LLC"
+    @business.draft.name
+    => "DraftPunk Inc"    
+    @business.publish_draft!
+    @business.draft.name = "DraftPunk Incorperated"
+    => "DraftPunk Incorperated"
+    @business.publish_draft!
+
+    @business.name
+    => "DraftPunk Incorperated"
+
+    @business.previous_versions.pluck(:name)
+    => ['DraftPunk Inc', 'DraftPunk LLC']
+
+    @business.previous_versions
+    => [Business(id: 2, name: 'DraftPunk Inc', ...), Business(id: 3, name: 'DraftPunk LLC', ...)]
+
+To enable this feature, add a `current_approved_version_id` column (Integer) to the model you call `requires_approval` on. Version history will be automatically tracked if that column is present.
+
+#### Prevent historic versions from being saved
+
+Since these are historic versions, and not the draft or the current live/approved version, you may want to prevent saving. In your model, set the `allow_previous_versions_to_be_changed` option, which adds a `before_save` callback halting any save.
+
+    requires_approval allow_previous_versions_to_be_changed: false
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -236,6 +289,24 @@ Or install it yourself as:
 
     $ gem install draft_punk
 
+## Why this gem compared to similar gems?
+
+I wrote this gem because other draft/publish gems had limitations that ruled them out in my use case. Here's a few reasons I ended up rolling my own:
+
+1. This gem simply works with your existing database (plus one new column on your original object).
+2. I tried using an approach that stores incremental changes in another table. For instance, some draft gems rely on a Versioning gem, or otherwise store incremental changes in the database.
+
+    That gets super complicated, or simply don't work, with associations, nested associations, and/or if you want users to be able to *edit* those changes.
+3. This gem works with Rails `accepts_nested_attributes`. That Rails pattern doesn't work when you pass in objects which aren't associated; for instance, if you try to save a new draft image on your Blog post via nested_attributes, Rails will throw a 404 error. It got nasty, fast, so I needed a solution that worked well with Rails.
+4. I prefer to store drafts in the same table as the original. While this has a downside (see downsides, below), it means:
+    1. Your draft acts like the original. You can execute all the same methods on it, reuse presenters, forms, form_objects, decorators, or anything else. It doesn't just quack like a duck, it **is** a duck.
+
+    2. This prevents your table structure from getting out of sync. If you're using DraftPunk, when you add a new attribute to your model, or change a column, both your live/approved version and your draft version are affected. Using a different pattern, if they live in separate tables, you may need to run migrations on both tables (or, migrate the internals of a version diff if your draft gem relies on something like Paper Trail or VestalVersion)
+
+### Downsides
+
+Since DraftPunk saves in the same table as the original, your queries in those tables will return both approved and draft objects. In other words, without modifying your Rails app further, your BusinessController index action (in a typical rails app) will return drafts and approved objects. DraftPunk adds scopes to help you manage this. See the "What about the rest of the application? People are seeing draft businesses!" section below for two patterns to address this. 
+
 ## Contributing
 
 1. Fork it ( https://github.com/stevehodges/draft_punk/fork )
@@ -244,3 +315,20 @@ Or install it yourself as:
 4. Commit your changes (`git commit -am 'Add some feature'`)
 5. Push to the branch (`git push origin my-new-feature`)
 6. Create a new Pull Request
+
+## Testing the gem
+
+To test the gem against the current version of Rails (in [Gemfile.lock](Gemfile.lock)):
+
+1. `bundle install`
+2. `bundle exec rspec`
+
+Or, you can run tests for all supported Rails versions
+
+1. `gem install appraisal`
+1. `bundle exec appraisal install` *(this Generates gemfiles for all permutations of our dependencies, so you'll see lots of bundler output))*
+1. `bundle exec appraisal rspec`. *(This runs rspec for each dependency permutation. If one fails, appraisal exits immediately and does not test permutations it hasn't gotten to yet. Tests are not considered passing until all permutations are passing)*
+
+If you only want to test a certain dependency set, such as Rails 5.2: `bundle exec appraisal rails-5-2 rspec`.
+
+You can view all available dependency sets in [Appraisals](Appraisals)

data/draft_punk.gemspec

@@ -33,11 +33,13 @@ EOF
 
   spec.add_runtime_dependency     "amoeba",    "~> 3.1"
   spec.add_runtime_dependency     "differ",    "< 0.2"
-  spec.add_runtime_dependency     'rails',     "> 5.0", "< 5.3"
+  spec.add_runtime_dependency     'rails',     ">= 5.0", "< 5.3"
 
   spec.add_development_dependency "bundler",   "~> 1.9"
   spec.add_development_dependency "rake",      "~> 10.0"
   spec.add_development_dependency "rspec",     "~> 2.0"
+  spec.add_development_dependency 'appraisal', '~> 2.2'
+  spec.add_development_dependency "timecop",   "~> 0.1"
   spec.add_development_dependency "sqlite3",   "~> 1.0"
   spec.add_development_dependency "yard",      "< 1.0"
 

data/lib/activerecord_class_methods.rb

@@ -1,5 +1,6 @@
 require 'activerecord_instance_methods'
 require 'draft_diff_instance_methods'
+require 'previous_version_instance_methods'
 
 module DraftPunk
   module Model
@@ -42,22 +43,24 @@ module DraftPunk
       #    persist those on the draft.
       # @param set_default_scope [Boolean] If true, set a default scope on this model for the approved scope; only approved objects
       #    will be returned in ActiveRecord queries, unless you call Model.unscoped
+      # @param allow_previous_versions_to_be_changed [Boolean] If the model tracks approved version history, and this
+      #    param is false, previously-approved versions of the object cannot be saved (via a before_save callback )
       # @param associations [Array] Use internally; set associations to create drafts for in the CREATES_NESTED_DRAFTS_FOR constant
       # @return true
-      def requires_approval(associations: [], nullify: [], set_default_scope: false)
+      def requires_approval(associations: [], nullify: [], set_default_scope: false, allow_previous_versions_to_be_changed: true)
         return unless draft_punk_table_exists?(table_name) # Short circuits if you're migrating
 
         associations = draft_target_associations if associations.empty?
         set_valid_associations(associations)
 
-        raise DraftPunk::ConfigurationError, "Cannot call requires_approval multiple times for #{name}" if const_defined? :DRAFT_PUNK_IS_SETUP
-        self.const_set :DRAFT_NULLIFY_ATTRIBUTES, [nullify].flatten
+        raise DraftPunk::ConfigurationError, "Cannot call requires_approval multiple times for #{name}" if const_defined?(:DRAFT_PUNK_IS_SETUP)
+        self.const_set :DRAFT_NULLIFY_ATTRIBUTES, Array(nullify).flatten.freeze
 
         amoeba do
           nullify nullify
           # Note that the amoeba associations and customize options are being set in setup_associations_and_scopes_for
         end
-        setup_amoeba_for self, set_default_scope: set_default_scope
+        setup_amoeba_for self, set_default_scope: set_default_scope, allow_previous_versions_to_be_changed: allow_previous_versions_to_be_changed
         true
       end
 
@@ -65,8 +68,9 @@ module DraftPunk
       # called multiple times. Only the usage for that use case is supported. Use at your own risk for other
       # use cases.
       def disable_approval!
-        send(:remove_const, :DRAFT_PUNK_IS_SETUP) if const_defined? :DRAFT_PUNK_IS_SETUP
-        send(:remove_const, :DRAFT_NULLIFY_ATTRIBUTES) if const_defined? :DRAFT_NULLIFY_ATTRIBUTES
+        send(:remove_const, :DRAFT_PUNK_IS_SETUP)                   if const_defined? :DRAFT_PUNK_IS_SETUP
+        send(:remove_const, :DRAFT_NULLIFY_ATTRIBUTES)              if const_defined? :DRAFT_NULLIFY_ATTRIBUTES
+        send(:remove_const, :ALLOW_PREVIOUS_VERSIONS_TO_BE_CHANGED) if const_defined? :ALLOW_PREVIOUS_VERSIONS_TO_BE_CHANGED
         fresh_amoeba do
           disable
         end
@@ -90,6 +94,14 @@ module DraftPunk
         column_names.include? 'approved_version_id'
       end
 
+      # Whether this model is configured to store previously-approved versions of the model.
+      # This will be true if the model has an current_approved_version_id column
+      #
+      # @return (Boolean)
+      def tracks_approved_version_history?
+        column_names.include?('current_approved_version_id')
+      end
+
     protected #################################################################
 
       def default_draft_target_associations
@@ -114,13 +126,13 @@ module DraftPunk
             false
           end
         end
-        self.const_set :DRAFT_VALID_ASSOCIATIONS, valid_assocations
+        self.const_set :DRAFT_VALID_ASSOCIATIONS, valid_assocations.freeze
         valid_assocations
       end
 
     private ###################################################################
 
-      def setup_amoeba_for(target_class, set_default_scope: false)
+      def setup_amoeba_for(target_class, options={})
         return if target_class.const_defined?(:DRAFT_PUNK_IS_SETUP)
         associations = target_class.draft_target_associations
         associations = target_class.set_valid_associations(associations)
@@ -129,9 +141,9 @@ module DraftPunk
           include_associations target_class.const_get(:DRAFT_VALID_ASSOCIATIONS) unless target_class.const_get(:DRAFT_VALID_ASSOCIATIONS).empty?
           customize target_class.set_approved_version_id_callback
         end
-        target_class.const_set :DRAFT_PUNK_IS_SETUP, true
+        target_class.const_set :DRAFT_PUNK_IS_SETUP, true.freeze
 
-        setup_associations_and_scopes_for target_class, set_default_scope: set_default_scope
+        setup_associations_and_scopes_for target_class, **options
         setup_draft_association_persistance_for_children_of target_class, associations
       end
 
@@ -157,11 +169,23 @@ module DraftPunk
         end
       end
 
-      def setup_associations_and_scopes_for(target_class, set_default_scope: false)
+      def setup_associations_and_scopes_for(target_class, set_default_scope: false, allow_previous_versions_to_be_changed: true)
         target_class.send       :include, InstanceInterrogators unless target_class.method_defined?(:has_draft?)
         target_class.send       :attr_accessor, :temporary_approved_object
         target_class.send       :before_create, :before_create_draft if target_class.method_defined?(:before_create_draft)
 
+        target_class.const_set :ALLOW_PREVIOUS_VERSIONS_TO_BE_CHANGED, allow_previous_versions_to_be_changed.freeze
+        if target_class.tracks_approved_version_history?
+          target_class.belongs_to    :current_approved_version, class_name: target_class.name, optional: true
+          target_class.has_many      :previous_versions, -> { order(id: :desc) }, class_name: target_class.name, foreign_key: :current_approved_version_id
+          target_class.before_update :prevent_previous_versions_from_saving
+          target_class.send          :include, PreviousVersionInstanceMethods
+        end
+
+        if set_default_scope
+          target_class.default_scope -> { approved }
+        end
+
         return if target_class.reflect_on_association(:approved_version) || !target_class.column_names.include?('approved_version_id')
         target_class.send       :include, ActiveRecordInstanceMethods
         target_class.send       :include, DraftDiffInstanceMethods
@@ -169,13 +193,9 @@ module DraftPunk
         target_class.scope      :approved, -> { where("#{target_class.quoted_table_name}.approved_version_id IS NULL") }
         target_class.has_one    :draft, -> { unscope(where: :approved) }, class_name: target_class.name, foreign_key: :approved_version_id
         target_class.scope      :draft, -> { unscoped.where("#{target_class.quoted_table_name}.approved_version_id IS NOT NULL") }
-        if set_default_scope
-          target_class.default_scope -> { approved }
-        end
       end
 
       def is_relevant_association_type?(activerecord_reflection)
-        # Note when implementing for Rails 4, macro is renamed to something else
         activerecord_reflection.macro.in? Amoeba::Config::DEFAULTS[:known_macros]
       end
 

data/lib/activerecord_instance_methods.rb

@@ -6,17 +6,6 @@ module DraftPunk
       # You can overwrite these methods in your model for custom behavior
       #############################
 
-      # Determines whether to edit a draft, or the original object. This only controls
-      # the object returned by editable version, and draft publishing. If changes to not
-      # require approval, publishing of the draft is short circuited and will do nothing.
-      #
-      # Overwrite in your model to implement logic for whether to use a draft.
-      #
-      # @return [Boolean]
-      def changes_require_approval?
-        true # By default, all changes require approval
-      end
-
       # Which attributes of this model are published from the draft to the approved object. Overwrite in model
       # if you don't want all attributes of the draft to be saved on the live object.
       #
@@ -36,6 +25,17 @@ module DraftPunk
         self.attributes.keys - ["created_at"]
       end
 
+      # Determines whether to edit a draft, or the original object. This only controls
+      # the object returned by editable version, and draft publishing. If changes to not
+      # require approval, publishing of the draft is short circuited and will do nothing.
+      #
+      # Overwrite in your model to implement logic for whether to use a draft.
+      #
+      # @return [Boolean]
+      def changes_require_approval?
+        true # By default, all changes require approval
+      end
+
       # Evaluates after the draft is created.
       # Override in your model to implement custom behavior.
       def after_create_draft
@@ -58,9 +58,9 @@ module DraftPunk
       def publish_draft!
         @live_version  = get_approved_version
         @draft_version = editable_version
-        return unless changes_require_approval? && @draft_version.is_draft? # No-op. ie. the business is in a state that doesn't require approval.
-
+        return unless changes_require_approval? && @draft_version.is_draft? # No-op. ie. the live version is in a state that doesn't require approval.
         transaction do
+          create_historic_version_of_approved_object if tracks_approved_version_history?
           save_attribute_changes_and_belongs_to_assocations_from_draft
           update_has_many_and_has_one_associations_from_draft
           # We have to destroy the draft this since we moved all the draft's has_many associations to @live_version. If you call "editable_version" later, it'll build the draft.
@@ -86,6 +86,10 @@ module DraftPunk
         approved_version || self
       end
 
+      def tracks_approved_version_history?
+        self.class.tracks_approved_version_history?
+      end
+
     protected #################################################################
 
       def get_draft
@@ -109,6 +113,21 @@ module DraftPunk
         draft
       end
 
+      def create_historic_version_of_approved_object
+        begin
+          dupe = @live_version.amoeba_dup
+          dupe.assign_attributes(
+                     approved_version_id: nil,
+             current_approved_version_id: @live_version.id,
+                              created_at: @live_version.created_at,
+                              updated_at: @live_version.updated_at )
+          dupe.save!(validate: false)
+        rescue => message
+          raise HistoricVersionCreationError, message
+        end
+        true
+      end
+
       def save_attribute_changes_and_belongs_to_assocations_from_draft
         @draft_version.attributes.each do |attribute, value|
           next unless attribute.in? usable_approvable_attributes
@@ -120,8 +139,7 @@ module DraftPunk
 
       def update_has_many_and_has_one_associations_from_draft
         self.class.draft_target_associations.each do |assoc|
-          reflection = self.class.reflect_on_association(assoc)
-
+          reflection = self.class.reflect_on_association(assoc) || next
           reflection_is_has_many(reflection) ? @live_version.send(assoc).destroy_all : @live_version.send(assoc).try(:destroy)
 
           attribute_updates = {}
@@ -129,13 +147,17 @@ module DraftPunk
           attribute_updates['updated_at']           = Time.now if reflection.klass.column_names.include?('updated_at')
           attribute_updates['approved_version_id']  = nil if reflection.klass.tracks_approved_version?
 
-          reflection_is_has_many(reflection) ? @draft_version.send(assoc).update_all(attribute_updates) : @draft_version.send(assoc).update_columns(attribute_updates)
+          if reflection_is_has_many(reflection)
+            @draft_version.send(assoc).update_all attribute_updates
+          elsif @draft_version.send(assoc).present?
+            @draft_version.send(assoc).update_columns attribute_updates
+          end
         end
       end
 
       def usable_approvable_attributes
         nullified_attributes = self.class.const_defined?(:DRAFT_NULLIFY_ATTRIBUTES) ? self.class.const_get(:DRAFT_NULLIFY_ATTRIBUTES) : []
-        approvable_attributes.map(&:to_s) - nullified_attributes.map(&:to_s) - ['approved_version_id', 'id']
+        approvable_attributes.map(&:to_s) - nullified_attributes.map(&:to_s) - ['approved_version_id', 'id', 'current_approved_version_id']
       end
 
       def current_approvable_attributes
@@ -150,15 +172,12 @@ module DraftPunk
       end
 
       def association_is_has_many(name)
-        # Note when implementing for Rails 4, macro is renamed to something else
         self.class.reflect_on_association(name.to_sym).macro == :has_many
       end
 
       def reflection_is_has_many(reflection)
-        # Note when implementing for Rails 4, macro is renamed to something else
         reflection.macro == :has_many
       end
-
     end
 
     module InstanceInterrogators
@@ -173,7 +192,14 @@ module DraftPunk
         raise DraftPunk::ApprovedVersionIdError unless respond_to?(:approved_version_id)
         draft.present?
       end
-    end
 
+      # @return [Boolean] whether the current ActiveRecord object is a previously-approved
+      #    version of another instance of this class
+      def is_previous_version?
+        tracks_approved_version_history? &&
+        !is_draft? &&
+        current_approved_version_id.present?
+      end
+    end
   end
 end

data/lib/draft_punk.rb

@@ -25,7 +25,16 @@ module DraftPunk
       @message = message
     end
     def to_s
-    	"this model doesn't have an approved_version_id column, so you cannot access its draft or approved versions. Add a column approved_version_id (Integer) to enable this tracking."
+      "this model doesn't have an approved_version_id column, so you cannot access its draft or approved versions. Add a column approved_version_id (Integer) to enable this tracking."
+    end
+  end
+
+  class HistoricVersionCreationError < ArgumentError
+    def initialize(message=nil)
+      @message = message
+    end
+    def to_s
+      "could not create previously-approved version: #{@message}"
     end
   end
 

data/lib/draft_punk/version.rb

@@ -1,3 +1,3 @@
 module DraftPunk
-  VERSION = "0.2.8"
+  VERSION = "0.3.0"
 end

data/lib/previous_version_instance_methods.rb

@@ -0,0 +1,41 @@
+module DraftPunk
+  module Model
+    module PreviousVersionInstanceMethods
+
+      # If the current object A is in the previous version history of a
+      # object B, this method updates B to match the approvable attributes
+      # and associations of A. A copy of B is added to the previous version
+      # history.
+      #
+      # @return [Activerecord Object] updated version of the approved object
+      def make_current!
+        return unless is_previous_version?
+        @live_version = current_approved_version
+        @previous_version = self
+        @live_version.draft.try(:destroy)
+        @previous_version.update_attributes(
+          current_approved_version_id: nil,
+                     approved_version: @live_version)
+        @live_version.publish_draft!
+      end
+
+      # @return [Activerecord Object]
+      def previous_version
+        previous_versions.first
+      end
+
+    private ###################################################################
+
+      # before_save
+      def prevent_previous_versions_from_saving
+        if is_previous_version? &&
+          self.class.const_defined?(:ALLOW_PREVIOUS_VERSIONS_TO_BE_CHANGED) &&
+          !self.class::ALLOW_PREVIOUS_VERSIONS_TO_BE_CHANGED
+          errors.add :base, 'cannot save previously approved version'
+          throw :abort 
+        end
+      end
+
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: draft_punk
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.3.0
 platform: ruby
 authors:
 - Steve Hodges
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-08-28 00:00:00.000000000 Z
+date: 2018-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: amoeba
@@ -42,7 +42,7 @@ dependencies:
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
     - - "<"
@@ -52,7 +52,7 @@ dependencies:
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
     - - "<"
@@ -100,6 +100,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -145,6 +173,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- Appraisals
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -162,6 +191,7 @@ files:
 - lib/draft_punk.rb
 - lib/draft_punk/version.rb
 - lib/helper_methods.rb
+- lib/previous_version_instance_methods.rb
 homepage: https://github.com/stevehodges/draftpunk
 licenses:
 - MIT