Improve gem docs (#5)

* Add toggle to turn on/off the gem

* Improve gem docs

* Update Martin Email

Co-authored-by: Martin Jaime <[email protected]>

README.md

@@ -1,6 +1,10 @@
 # ChaoticOrder
 
-Chaotic Order is a simple gem to help you detect queries that are missing an order. Sometimes we don't add an order because we assume they are going to come back ordered by `id` or something else, but it is not guaranteed by the DBMS. By forcing a randomic order to unordered queries we can help you detect them more easily. This gem can also help detecting intermittent tests that otherwise are hard to replicate.
+Chaotic Order helps you detect queries that are missing an order.
+
+Sometimes we forget to add an order to our queries, or we don't add it because we assume that by default they will be returned ordered by `id`, but that is not guaranteed by the DBMS. By forcing a randomic order to the unordered queries, we can help you detect them more easily.
+
+This gem can be useful helping detect intermittent tests that otherwise are hard to replicate.
 
 ## Installation
 
@@ -12,6 +16,8 @@ group :development, :test do
 end
 ```
 
+Note that this gem is not recommended to be used in production.
+
 And then execute:
 
     $ bundle install
@@ -22,7 +28,11 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+By default the gem is turned off, and there are two ways to turn it on:
+1. By setting an environment variable `CHAOTIC_ORDER=true`
+1. By calling `ChaoticOrder::Config.enable!` in a initializer
+
+In either option, make sure that you are only enabling it in development and/or test environments, depending on your needs.
 
 ## Development
 

chaotic_order.gemspec

@@ -5,25 +5,21 @@ require_relative "lib/chaotic_order/version"
 Gem::Specification.new do |spec|
   spec.name          = "chaotic_order"
   spec.version       = ChaoticOrder::VERSION
-  spec.authors       = ["Santiago Bartesaghi"]
-  spec.email         = ["[email protected]"]
+  spec.authors       = ["Santiago Bartesaghi", "Martin Jaime"]
+  spec.email         = ["[email protected]", "[email protected]"]
 
   spec.summary       = "Add random order to queries that do not have a specific order"
-  spec.description   = spec.summary
   spec.homepage      = "https://github.com/santib/chaotic_order"
   spec.license       = "MIT"
   spec.required_ruby_version = ">= 2.5.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/santib/chaotic_order/issues"
+  spec.metadata["source_code_uri"] = "https://github.com/santib/chaotic_order"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/santib/chaotic_order/issues"
   spec.metadata["changelog_uri"] = "https://github.com/santib/chaotic_order/releases"
   spec.metadata["rubygems_mfa_required"] = "true"
 
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
-  end
+  spec.files         = Dir["LICENSE.txt", "README.md", "lib/**/*"]
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]