mongoid_orderable 5.2.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: eb9edcb0b7e48f8910b7a098a650b2908e1ba5cf
-  data.tar.gz: c4ffa043177aa71c23f565d9e9d0765f94b4409c
+SHA256:
+  metadata.gz: 278b3da8970c3b04304f169db82ca4999f31cf6b1b2212dd632864e805238162
+  data.tar.gz: b0c174f214b091e08e88660f622554f362dfa08722117f914d1358017d3b86e5
 SHA512:
-  metadata.gz: 195681bcfce24cde2af7ebfb9b9ed74a36688ce24ec8acf59bc8f1b94c3ea81d3e252f1a20f67e4c554818c03739da3b84639026f5a80cb259575d7a2686f331
-  data.tar.gz: 51d3bb674839997759c72ef9aa88335900ff6e6f5859fd8809c5e81a14f733c18df29191485ff81257fbe5b16c693985fd60b75f0c4a3166f4e48c219067f258
+  metadata.gz: 73f36dbb8f62f5f252deaaed6f488ea423d92d52be039aa6d95b7b2e0457cf41d50a63d934d26b1b2d92ad9d44530ec5053ca639c81b1ee523a244fe6dfbf9fd
+  data.tar.gz: b5ce0f3b0de0e6a0653784f1a507b5e32a92e9f59e277fa27e020010cf6f3cf0d5f49cc685c58e8ffe8a0ba0493d7d9cf41f0ddc3f13fc79a155b16e2f409f5b

data/CHANGELOG.md

@@ -1,58 +1,73 @@
-### 5.2.0 (2018/05/01)
-
-* [#57](https://github.com/mongoid/mongoid_orderable/pull/57): Compatibility with Mongoid 7 - [@tomasc](https://github.com/tomasc).
-* [#52](https://github.com/mongoid/mongoid_orderable/pull/52): Test against Mongoid 6 - [@dblock](https://github.com/dblock).
-
-### 5.1.0 (2017/06/04)
-
-* [#50](https://github.com/mongoid/mongoid_orderable/pull/50): Added Danger, PR linter - [@dblock](https://github.com/dblock).
-* [#51](https://github.com/mongoid/mongoid_orderable/pull/51): Added RuboCop - [@dblock](https://github.com/dblock).
-* [#49](https://github.com/mongoid/mongoid_orderable/pull/49): Fix orderable on embedded documents inside an inherited model - [@rafaelgaspar](https://github.com/rafaelgaspar).
-
-### 5.0.0 (2015/10/21)
-
-* [#41](https://github.com/mongoid/mongoid_orderable/pull/41): Mongoid 5 support - [@dblock](https://github.com/dblock).
-* [#41](https://github.com/mongoid/mongoid_orderable/pull/41): Dropped support for ruby 1.8 - [@dblock](https://github.com/dblock).
-
-### 4.1.1 (2014/12/19)
-
-* [#34](https://github.com/mongoid/mongoid_orderable/pull/34): Fix: index should respect scope - [@joeyAghion](https://github.com/joeyAghion).
-
-### 4.1.0 (2014/3/19)
-
-* [#30](https://github.com/mongoid/mongoid_orderable/pull/30): Fix: reset a single column when `orderable_scope` changed instead of removing it from list - [@Bharat311](https://github.com/Bharat311).
-* [#29](https://github.com/mongoid/mongoid_orderable/pull/29): Fix: incorrect position when orderable base is set - [@Bharat311](https://github.com/Bharat311).
-* [#28](https://github.com/mongoid/mongoid_orderable/pull/28): Inherited `orderable_configurations` - [@johnny-miyake](https://github.com/johnny-miyake).
-* [#27](https://github.com/mongoid/mongoid_orderable/pull/27): Allowed numeric string to specify a target position - [@johnny-miyake](https://github.com/johnny-miyake).
-* [#26](https://github.com/mongoid/mongoid_orderable/pull/26): Added support for multiple orderable columns - [@Bharat311](https://github.com/Bharat311).
-* [#22](https://github.com/mongoid/mongoid_orderable/pull/22): Added lazy support for scopes with different foreign key names - [@dsci](https://github.com/dsci).
-* [#21](https://github.com/mongoid/mongoid_orderable/pull/21): Accounting for change in Mongoid's metadata API - [@pjkelly](https://github.com/pjkelly).
-* [#20](https://github.com/mongoid/mongoid_orderable/pull/20): Added next and previous item methods - [@mrjlynch](https://github.com/mrjlynch).
-* [#19](https://github.com/mongoid/mongoid_orderable/pull/19): Added lower and higher item methods - [@mrjlynch](https://github.com/mrjlynch).
-
-### 4.0.0 (2013/10/22)
-
-* [#18](https://github.com/mongoid/mongoid_orderable/pull/18): Added Mongoid 4 support - [@dblock](https://github.com/dblock).
-* [#16](https://github.com/mongoid/mongoid_orderable/pull/16): Fix for Mongoid identity map combined with scoped orderable - [@johnnyshields](https://github.com/johnnyshields).
-* [#15](https://github.com/mongoid/mongoid_orderable/pull/15): Support pass-thru of Mongoid field alias (`:as` parameter) - [@johnnyshields](https://github.com/johnnyshields).
-* [#13](https://github.com/mongoid/mongoid_orderable/pull/13): Support inheritance - [@zhengjia](https://github.com/zhengjia).
-
-### 1.2.0 (2013/1/10)
-
-* [#12](https://github.com/mongoid/mongoid_orderable/pull/12): Added support for "base" in config options, in order to do a zero-based position - [@johnnyshields](https://github.com/johnnyshields).
-
-### 1.1.0 (2012/5/23)
-
-* Added Mongoid 3 support - [@pyromaniac](https://github.com/pyromaniac).
-
-### 1.0.0 (2012/2/14)
-
-* [#5](https://github.com/mongoid/mongoid_orderable/pull/5): Allow for use with default scopes - [@mattiassvedhem](https://github.com/mattiassvedhem).
-
-### 0.9.1 (2012/2/3)
-
-### 0.9.0 (2011/11/23)
-
-### 0.0.1 (2011/11/1)
-
-* Initial public release - [@pyromaniac](https://github.com/pyromaniac).
+### 6.0.1 (Next)
+
+* Your contribution here.
+
+### 6.0.0 (2021/01/23)
+
+* [#65](https://github.com/mongoid/mongoid_orderable/pull/65): Feature: Add transaction support with lock table - [@johnnyshields](https://github.com/johnnyshields).
+* [#65](https://github.com/mongoid/mongoid_orderable/pull/65): Feature: Avoid calling position function if neither position nor scope is changing - [@johnnyshields](https://github.com/johnnyshields).
+* [#62](https://github.com/mongoid/mongoid_orderable/pull/62): Feature: Allow scope parameter to be an Array - [@johnnyshields](https://github.com/johnnyshields).
+* [#62](https://github.com/mongoid/mongoid_orderable/pull/62): Feature: Add global configurability - [@johnnyshields](https://github.com/johnnyshields).
+* [#65](https://github.com/mongoid/mongoid_orderable/pull/65): Fix: Do not run embedded destroy callbacks when the root object has been destroyed - [@johnnyshields](https://github.com/johnnyshields).
+* [#62](https://github.com/mongoid/mongoid_orderable/pull/62): Refactor: rename "column" to "field" - [@johnnyshields](https://github.com/johnnyshields).
+* [#60](https://github.com/mongoid/mongoid_orderable/pull/60): Refactor: Drop support for Mongoid 6.x and lower - [@johnnyshields](https://github.com/johnnyshields).
+* [#60](https://github.com/mongoid/mongoid_orderable/pull/60): Refactor: Remove Mongoid Compatibility (no longer needed) - [@johnnyshields](https://github.com/johnnyshields).
+
+### 5.2.0 (2018/05/01)
+
+* [#57](https://github.com/mongoid/mongoid_orderable/pull/57): Compatibility with Mongoid 7 - [@tomasc](https://github.com/tomasc).
+* [#52](https://github.com/mongoid/mongoid_orderable/pull/52): Test against Mongoid 6 - [@dblock](https://github.com/dblock).
+
+### 5.1.0 (2017/06/04)
+
+* [#50](https://github.com/mongoid/mongoid_orderable/pull/50): Added Danger, PR linter - [@dblock](https://github.com/dblock).
+* [#51](https://github.com/mongoid/mongoid_orderable/pull/51): Added RuboCop - [@dblock](https://github.com/dblock).
+* [#49](https://github.com/mongoid/mongoid_orderable/pull/49): Fix orderable on embedded documents inside an inherited model - [@rafaelgaspar](https://github.com/rafaelgaspar).
+
+### 5.0.0 (2015/10/21)
+
+* [#41](https://github.com/mongoid/mongoid_orderable/pull/41): Mongoid 5 support - [@dblock](https://github.com/dblock).
+* [#41](https://github.com/mongoid/mongoid_orderable/pull/41): Dropped support for ruby 1.8 - [@dblock](https://github.com/dblock).
+
+### 4.1.1 (2014/12/19)
+
+* [#34](https://github.com/mongoid/mongoid_orderable/pull/34): Fix: index should respect scope - [@joeyAghion](https://github.com/joeyAghion).
+
+### 4.1.0 (2014/3/19)
+
+* [#30](https://github.com/mongoid/mongoid_orderable/pull/30): Fix: reset a single field when `orderable_scope` changed instead of removing it from list - [@Bharat311](https://github.com/Bharat311).
+* [#29](https://github.com/mongoid/mongoid_orderable/pull/29): Fix: incorrect position when orderable base is set - [@Bharat311](https://github.com/Bharat311).
+* [#28](https://github.com/mongoid/mongoid_orderable/pull/28): Inherited `orderable_configurations` - [@johnny-miyake](https://github.com/johnny-miyake).
+* [#27](https://github.com/mongoid/mongoid_orderable/pull/27): Allowed numeric string to specify a target position - [@johnny-miyake](https://github.com/johnny-miyake).
+* [#26](https://github.com/mongoid/mongoid_orderable/pull/26): Added support for multiple orderable fields - [@Bharat311](https://github.com/Bharat311).
+* [#22](https://github.com/mongoid/mongoid_orderable/pull/22): Added lazy support for scopes with different foreign key names - [@dsci](https://github.com/dsci).
+* [#21](https://github.com/mongoid/mongoid_orderable/pull/21): Accounting for change in Mongoid's metadata API - [@pjkelly](https://github.com/pjkelly).
+* [#20](https://github.com/mongoid/mongoid_orderable/pull/20): Added next and previous item methods - [@mrjlynch](https://github.com/mrjlynch).
+* [#19](https://github.com/mongoid/mongoid_orderable/pull/19): Added lower and higher item methods - [@mrjlynch](https://github.com/mrjlynch).
+
+### 4.0.0 (2013/10/22)
+
+* [#18](https://github.com/mongoid/mongoid_orderable/pull/18): Added Mongoid 4 support - [@dblock](https://github.com/dblock).
+* [#16](https://github.com/mongoid/mongoid_orderable/pull/16): Fix for Mongoid identity map combined with scoped orderable - [@johnnyshields](https://github.com/johnnyshields).
+* [#15](https://github.com/mongoid/mongoid_orderable/pull/15): Support pass-thru of Mongoid field alias (`:as` parameter) - [@johnnyshields](https://github.com/johnnyshields).
+* [#13](https://github.com/mongoid/mongoid_orderable/pull/13): Support inheritance - [@zhengjia](https://github.com/zhengjia).
+
+### 1.2.0 (2013/1/10)
+
+* [#12](https://github.com/mongoid/mongoid_orderable/pull/12): Added support for "base" in config options, in order to do a zero-based position - [@johnnyshields](https://github.com/johnnyshields).
+
+### 1.1.0 (2012/5/23)
+
+* Added Mongoid 3 support - [@pyromaniac](https://github.com/pyromaniac).
+
+### 1.0.0 (2012/2/14)
+
+* [#5](https://github.com/mongoid/mongoid_orderable/pull/5): Allow for use with default scopes - [@mattiassvedhem](https://github.com/mattiassvedhem).
+
+### 0.9.1 (2012/2/3)
+
+### 0.9.0 (2011/11/23)
+
+### 0.0.1 (2011/11/1)
+
+* Initial public release - [@pyromaniac](https://github.com/pyromaniac).

data/LICENSE.txt

@@ -1,20 +1,20 @@
-Copyright (c) 2011-2017 Arkadiy Zabazhanov & Contributors
-
-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.
+Copyright (c) 2011-2017 Arkadiy Zabazhanov & Contributors
+
+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

@@ -1,150 +1,256 @@
-[![Gem Version](https://badge.fury.io/rb/mongoid_orderable.svg)](https://badge.fury.io/rb/mongoid_orderable)
-[![Build Status](https://travis-ci.org/mongoid/mongoid_orderable.svg?branch=master)](https://travis-ci.org/mongoid/mongoid_orderable)
-
-# What?
-
-Mongoid::Orderable is a ordered list implementation for your Mongoid 3, 4, 5, 6 and 7 models.
-
-# Why?
-
-* It uses native mongo batch increment feature
-* It supports mutators api
-* It correctly assigns the position while moving document between scopes
-* It supports specifying multiple orderable columns
-
-# How?
-
-```ruby
-gem 'mongoid_orderable'
-```
-
-Gem has the same api as others. Just include Mongoid::Orderable into your model and call `orderable` method.
-Embedded objects are automatically scoped by their parent.
-
-```ruby
-class Item
-  include Mongoid::Document
-  include Mongoid::Orderable
-
-  # belongs_to :group
-  # belongs_to :drawer, class_name: "Office::Drawer",
-  #            foreign_key: "legacy_drawer_key_id"
-
-  # orderable
-  # orderable scope: :group, column: :pos
-  # orderable scope: :drawer, column: :pos # resolves scope foreign key from relation
-  # orderable scope: 'drawer', column: :pos # but if you pass a string - it will use it as is, as the column name for scope
-  # orderable scope: lambda { |document| where(group_id: document.group_id) }
-  # orderable index: false # this one if you want specify indexes manually
-  # orderable base: 0 # count position from zero as the top-most value (1 is the default value)
-end
-```
-
-# Usage
-
-```ruby
-item.move_to 2 # just change position
-item.move_to! 2 # and save
-item.move_to = 2 # assignable method
-
-# symbol position
-item.move_to :top
-item.move_to :bottom
-item.move_to :higher
-item.move_to :lower
-
-# generated methods
-item.move_to_top
-item.move_to_bottom
-item.move_higher
-item.move_lower
-
-item.next_items # return a collection of items higher on the list
-item.previous_items # return a collection of items lower on the list
-
-item.next_item # returns the next item in the list
-item.previous_item # returns the previous item in the list
-```
-
-# Multiple Columns
-
-You can also define multiple orderable columns for any class including the Mongoid::Orderable module.
-
-```ruby
-class Book
-  include Mongoid::Document
-  include Mongoid::Orderable
-
-  orderable base: 0
-  orderable column: sno, as: :serial_no
-end
-```
-
-The above defines two different orderable_columns on Book - *position* and *serial_no*.
-The following helpers are generated in this case:
-
-```ruby
-item.move_#{column_name}_to
-item.move_#{column_name}_to=
-item.move_#{column_name}_to!
-
-item.move_#{column_name}_to_top
-item.move_#{column_name}_to_bottom
-item.move_#{column_name}_higher
-item.move_#{column_name}_lower
-
-item.next_#{column_name}_items
-item.previous_#{column_name}_items
-
-item.next_#{column_name}_item
-item.previous_#{column_name}_item
-```
-
-*where column_name is either **position** or  **serial_no**.*
-
-When a model defines multiple orderable columns, the original helpers are also available and work on the first orderable column.
-
-```ruby
-  @book1 = Book.create!
-  @book2 = Book.create!
-  @book2                 => #<Book _id: 53a16a2ba1bde4f746000001, serial_no: 1, position: 1>
-  @book2.move_to! :top   # this will change the :position of the book to 0 (not serial_no)
-  @book2                 => #<Book _id: 53a16a2ba1bde4f746000001, serial_no: 1, position: 0>
-```
-
-To specify any other orderable column as default pass the **default: true** option with orderable.
-
-```ruby
-  orderable column: sno, as: :serial_no, default: true
-```
-
-# Embedded documents
-```ruby
-class Question
-  include Mongoid::Document
-  include Mongoid::Orderable
-
-  embedded_in :survey
-
-  orderable
-end
-```
-If you bulk import embedded documents without specifying their position, no field `position` will be written.
-```ruby
-class Survey
-  include Mongoid::Document
-
-  embeds_many :questions, cascade_callbacks: true
-end
-```
-To ensure the position is written correctly, you will need to provide the cascade callbacks option to the relation.
-
-# Contributing
-
-See [CONTRIBUTING](CONTRIBUTING.md).
-
-# Copyright & License
-
-Copyright (c) 2011-2016 Arkadiy Zabazhanov & Contributors.
-
-MIT license, see [LICENSE](LICENSE.txt) for details.
+[![Gem Version](https://badge.fury.io/rb/mongoid_orderable.svg)](https://badge.fury.io/rb/mongoid_orderable)
+[![Build Status](https://travis-ci.org/mongoid/mongoid_orderable.svg?branch=master)](https://travis-ci.org/mongoid/mongoid_orderable)
+
+# Mongoid Orderable
+
+Mongoid::Orderable is a ordered list implementation for your Mongoid 7+ projects.
+
+### Core Features
+
+* Sets a position index field on your documents which allows you to sort them in order.
+* Uses MongoDB's `$inc` operator to batch-update position.
+* Supports scope for position index, including changing scopes.
+* Supports multiple position indexes on the same document.
+* (Optional) Uses [MongoDB transactions](https://docs.mongodb.com/manual/core/transactions/) to ensure order integrity during concurrent updates.
+
+### Version Support
+
+As of version 6.0.0, Mongoid::Orderable supports the following dependency versions:
+
+* Ruby 2.6+
+* Mongoid 7.0+
+* Rails 5.2+
+
+For older versions, please use Mongoid::Orderable 5.x and earlier.
+
+Transaction support requires MongoDB 4.2+ (4.4+ recommended.)
+
+## Usage
+
+### Getting Started
+
+```ruby
+gem 'mongoid_orderable'
+```
+
+Include `Mongoid::Orderable` into your model and call `orderable` method.
+Embedded objects are automatically scoped to their parent.
+
+```ruby
+class MyModel
+  include Mongoid::Document
+  include Mongoid::Orderable
+
+  belongs_to :group
+  belongs_to :drawer, class_name: "Office::Drawer",
+             foreign_key: "legacy_drawer_key_id"
+
+  orderable
+
+  # if you set :scope as a symbol, it will resolve the foreign key from relation
+  orderable scope: :drawer, field: :pos
+
+  # if you set :scope as a string, it will use it as the field name for scope
+  orderable scope: 'drawer', field: :pos
+
+  # scope can also be a proc
+  orderable scope: ->(doc) { where(group_id: doc.group_id) }
+
+  # this one if you want specify indexes manually
+  orderable index: false 
+
+  # count position from zero as the top-most value (1 is the default value)
+  orderable base: 0
+end
+```
+
+You can also set default config values in an initializer, which will be
+applied when calling the `orderable` macro in a model.
+
+```ruby
+# configs/initializers/mongoid_orderable.rb
+Mongoid::Orderable.configure do |config|
+  config.field = :pos
+  config.base = 0
+  config.index = false
+end
+```
+
+### Moving Position
+
+```ruby
+item.move_to 2 # just change position
+item.move_to! 2 # and save
+item.move_to = 2 # assignable method
+
+# symbol position
+item.move_to :top
+item.move_to :bottom
+item.move_to :higher
+item.move_to :lower
+
+# generated methods
+item.move_to_top
+item.move_to_bottom
+item.move_higher
+item.move_lower
+
+item.next_items # return a collection of items higher on the list
+item.previous_items # return a collection of items lower on the list
+
+item.next_item # returns the next item in the list
+item.previous_item # returns the previous item in the list
+```
+
+### Multiple Fields
+
+You can also define multiple orderable fields for any class including the Mongoid::Orderable module.
+
+```ruby
+class Book
+  include Mongoid::Document
+  include Mongoid::Orderable
+
+  orderable base: 0
+  orderable field: sno, as: :serial_no
+end
+```
+
+The above defines two different orderable_fields on Book - *position* and *serial_no*.
+The following helpers are generated in this case:
+
+```ruby
+book.move_#{field}_to
+book.move_#{field}_to=
+book.move_#{field}_to!
+
+book.move_#{field}_to_top
+book.move_#{field}_to_bottom
+book.move_#{field}_higher
+book.move_#{field}_lower
+
+book.next_#{field}_items
+book.previous_#{field}_items
+
+book.next_#{field}_item
+book.previous_#{field}_item
+```
+
+where `#{field}` is either `position` or `serial_no`.
+
+When a model defines multiple orderable fields, the original helpers are also available and work on the first orderable field.
+
+```ruby
+  @book1 = Book.create!
+  @book2 = Book.create!
+  @book2                 # => <Book _id: 53a16a2ba1bde4f746000001, serial_no: 1, position: 1>
+  @book2.move_to! :top   # this will change the :position of the book to 0 (not serial_no)
+  @book2                 # => <Book _id: 53a16a2ba1bde4f746000001, serial_no: 1, position: 0>
+```
+
+To specify any other orderable field as default pass the **default: true** option with orderable.
+
+```ruby
+  orderable field: sno, as: :serial_no, default: true
+```
+
+### Embedded Documents
+
+```ruby
+class Question
+  include Mongoid::Document
+  include Mongoid::Orderable
+
+  embedded_in :survey
+
+  orderable
+end
+```
+
+If you bulk import embedded documents without specifying their position,
+no field `position` will be written.
+
+```ruby
+class Survey
+  include Mongoid::Document
+
+  embeds_many :questions, cascade_callbacks: true
+end
+```
+
+To ensure the position is written correctly, you will need to set
+`cascade_callbacks: true` on the relation.
+
+## Transaction Support
+
+By default, Mongoid Orderable does not guarantee ordering consistency
+when doing multiple concurrent updates on documents. This means that
+instead of having positions `1, 2, 3, 4, 5`, after running your system
+in production at scale your position data will become corrupted, e.g.
+`1, 1, 4, 4, 6`. To remedy this, this Mongoid Orderable can use
+[MongoDB transactions](https://docs.mongodb.com/manual/core/transactions/)
+
+### Prerequisites
+
+* MongoDB version 4.2+ (4.4+ recommended.)
+* Requires [MongoDB Replica Set](https://docs.mongodb.com/manual/tutorial/deploy-replica-set/) topology
+
+### Configuration
+
+You may enable transactions on both the global and model configs:
+
+```ruby
+Mongoid::Orderable.configure do |config|
+  config.use_transactions = true       # default: false
+  config.transaction_max_retries = 10  # default: 10
+end
+
+class MyModel
+  orderable :position, use_transactions: false
+end
+```
+
+When two transactions are attempted at the same time, database-level
+`WriteConflict` failures may result and retries will be attempted.
+After `transaction_max_retries` has been exceeded, a
+`Mongoid::Orderable::Errors::TransactionFailed` error will be raised.
+
+### Locks
+
+When using transactions, Mongoid Orderable creates a collection
+`mongoid_orderable_locks` which is used to store temporary lock objects.
+This collection accumulate documents overtime; it is safe to delete it periodically.
+
+You can change the lock collection name globally or per model:
+
+```ruby
+Mongoid::Orderable.configure do |config|
+  config.lock_collection = "my_locks"  # default: "mongoid_orderable_locks"
+end
+
+class MyModel
+  orderable :position, lock_collection: "my_model_locks"
+end
+```
+
+### MongoDB 4.2 Support
+
+In MongoDB 4.2, collections cannot be created within transactions.
+Therefore, you will need to manually run the following command once
+to initialize the lock collection:
+
+```ruby
+Mongoid::Orderable::Models::Lock.create!
+```
+
+This step is not necessary when using MongoDB 4.4+.
+
+### Contributing
+
+Please fork the project on Github and raise a pull request including passing specs.
+
+### Copyright & License
+
+Copyright (c) 2011 Arkadiy Zabazhanov, Johnny Shields, and contributors.
+
+MIT license, see [LICENSE](LICENSE.txt) for details.