workflow-activerecord 4.1.1.pre → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae6e5038a156d5f4e9e6e3fee2b230bc857b683ac75bb17a2c5d1910069e01b7
-  data.tar.gz: 6cb41ab01b13c94e84b57fa1a7daa0333053a48f813d8bcb3e0fa7b8d9b63346
+  metadata.gz: 6e4b0f04924472fad5ba5fe6b917c13bdc9b023ee21b5fc57a4362ee659cda3b
+  data.tar.gz: 9949cfc0c4677cdd75f821a8fc1fa86f781d30165fe2e492cd93d4115b9a39dc
 SHA512:
-  metadata.gz: 81fa68fcd2224a357bf70a10c263c9b59b4edb65abc181b86960d65f8cff479109dfebe6c6d2827caeb626b4840c7a131cfe402a403ebc6a544556515c6f8aaa
-  data.tar.gz: 43538661e4db5a82e01ae88a60c0b01753455e19b22c012e53f77568359a3c66ac192e4399394008478aa463fe700f07e7e6cb3c7a9212eb5d89923b0b059c45
+  metadata.gz: e2c87a9a399dd3c91f966cb2f87ea660400b3376053a9ca3a489189ea433f7962015f52aa4072bc956c5d9a56b6e5d324da6df3a7012c8181f20c659f26028a6
+  data.tar.gz: 31498bb866bcfded36c4eda93df32ece31c6fd0f53f71ba83a528e886f199290f8a3b7522814d63b219d1dc219925b5cfc77dc5894a2890faa9570cb7ce55081

data/README.md

@@ -13,12 +13,207 @@ Coverage](https://codeclimate.com/github/geekq/workflow-activerecord/badges/cove
 
 **ActiveRecord/Rails Integration for the Workflow library**
 
-To use `workflow` with a Rails 5.0 project you now need to include
+Major+minor versions of workflow-activerecord are based on the oldest
+compatible ActiveRecord API.  To use [`workflow`][] with a
+Rails/ActiveRecord 4.1, 4.2, 5.0, 5.1, 5.2 please use:
 
-    gem 'workflow-activerecord'
+    gem 'workflow-activerecord', '>= 4.1', '< 6.0'
 
-This will also automatically include the newest version of the core
-'workflow' gem. But you can also choose a specific version:
+This will also automatically include the newest compatible version of
+the core 'workflow' gem. But you can also choose a specific version:
 
     gem 'workflow', '~> 2.0'
-    gem 'workflow-activerecord'
+    gem 'workflow-activerecord', '>= 4.1pre', '< 6.0'
+
+Please also have a look at the [sample application][]!
+
+For detailed introduction into workflow DSL please read [`workflow`][]!
+
+[`workflow`]: https://github.com/geekq/workflow
+[sample application]: https://github.com/geekq/workflow-rails-sample
+
+
+State persistence with ActiveRecord
+-----------------------------------
+
+Workflow library can handle the state persistence fully automatically. You
+only need to define a string field on the table called `workflow_state`
+and include the workflow mixin in your model class as usual:
+
+    class Order < ApplicationRecord
+      include Workflow
+      workflow do
+        # list states and transitions here
+      end
+    end
+
+On a database record loading all the state check methods e.g.
+`article.state`, `article.awaiting_review?` are immediately available.
+For new records or if the `workflow_state` field is not set the state
+defaults to the first state declared in the workflow specification. In
+our example it is `:new`, so `Article.new.new?` returns true and
+`Article.new.approved?` returns false.
+
+At the end of a successful state transition like `article.approve!` the
+new state is immediately saved in the database.
+
+You can change this behaviour by overriding `persist_workflow_state`
+method.
+
+### Scopes
+
+Workflow library also adds automatically generated scopes with names based on
+states names:
+
+    class Order < ApplicationRecord
+      include Workflow
+      workflow do
+        state :approved
+        state :pending
+      end
+    end
+
+    # returns all orders with `approved` state
+    Order.with_approved_state
+
+    # returns all orders with `pending` state
+    Order.with_pending_state
+
+
+### Custom workflow database column
+
+[meuble](http://imeuble.info/) contributed a solution for using
+custom persistence column easily, e.g. for a legacy database schema:
+
+    class LegacyOrder < ApplicationRecord
+      include Workflow
+
+      workflow_column :foo_bar # use this legacy database column for
+                               # persistence
+    end
+
+
+
+### Single table inheritance
+
+Single table inheritance is also supported. Descendant classes can either
+inherit the workflow definition from the parent or override with its own
+definition.
+
+
+Custom Versions of Existing Adapters
+------------------------------------
+
+Other adapters (such as a custom ActiveRecord plugin) can be selected by adding a `workflow_adapter` class method, eg.
+
+```ruby
+class Example < ApplicationRecord
+  def self.workflow_adapter
+    MyCustomAdapter
+  end
+  include Workflow
+
+  # ...
+end
+```
+
+(The above will include `MyCustomAdapter` *instead* of the default
+`WorkflowActiverecord` adapter.)
+
+
+Multiple Workflows
+------------------
+
+I am frequently asked if it's possible to represent multiple "workflows"
+in an ActiveRecord class.
+
+The solution depends on your business logic and how you want to
+structure your implementation.
+
+### Use Single Table Inheritance
+
+One solution can be to do it on the class level and use a class
+hierarchy. You can use [single table inheritance][STI] so there is only
+single `orders` table in the database. Read more in the chapter "Single
+Table Inheritance" of the [ActiveRecord documentation][ActiveRecord].
+Then you define your different classes:
+
+    class Order < ActiveRecord::Base
+      include Workflow
+    end
+
+    class SmallOrder < Order
+      workflow do
+        # workflow definition for small orders goes here
+      end
+    end
+
+    class BigOrder < Order
+      workflow do
+        # workflow for big orders, probably with a longer approval chain
+      end
+    end
+
+
+### Individual workflows for objects
+
+Another solution would be to connect different workflows to object
+instances via metaclass, e.g.
+
+    # Load an object from the database
+    booking = Booking.find(1234)
+
+    # Now define a workflow - exclusively for this object,
+    # probably depending on some condition or database field
+    if # some condition
+      class << booking
+        include Workflow
+        workflow do
+          state :state1
+          state :state2
+        end
+      end
+    # if some other condition, use a different workflow
+
+You can also encapsulate this in a class method or even put in some
+ActiveRecord callback. Please also have a look at [the full working
+example][multiple_workflow_test]!
+
+[STI]: http://www.martinfowler.com/eaaCatalog/singleTableInheritance.html
+[ActiveRecord]: http://api.rubyonrails.org/classes/ActiveRecord/Base.html
+[multiple_workflow_test]: https://github.com/geekq/workflow-activerecord/blob/develop/test/multiple_workflows_test.rb
+
+
+Changelog
+---------
+
+### New in the version 4.1.0
+
+First version supporting Rails/ActiveRecord 4.1, 4.2, 5.0, 5.1, 5.2
+Special thanks to [@voltechs][] for implementing Rails 5 support
+and helping to revive `workflow`!
+
+[@voltechs]: https://github.com/voltechs
+
+Support
+-------
+
+### Reporting bugs
+
+<http://github.com/geekq/workflow-activerecord/issues>
+
+
+About
+-----
+
+Author: Vladimir Dobriakov, <https://infrastructure-as-code.de>
+
+Copyright (c) 2010-2019 Vladimir Dobriakov and Contributors
+
+Copyright (c) 2008-2009 Vodafone
+
+Copyright (c) 2007-2008 Ryan Allen, FlashDen Pty Ltd
+
+Based on the work of Ryan Allen and Scott Barron
+
+Licensed under MIT license, see the LICENSE file.

data/lib/workflow_activerecord/version.rb

@@ -1,3 +1,3 @@
 module WorkflowActiverecord
-  VERSION = "4.1.1.pre"
+  VERSION = "4.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workflow-activerecord
 version: !ruby/object:Gem::Version
-  version: 4.1.1.pre
+  version: 4.1.1
 platform: ruby
 authors:
 - Vladimir Dobriakov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-10 00:00:00.000000000 Z
+date: 2019-01-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: workflow
@@ -186,9 +186,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.7.6