handcuffs 1.4.1 → 2.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to Procore Projects
+
+This document explains the common procedures expected by contributors while submitting code to Procore open source projects.
+
+## Code of Conduct
+
+Please read and abide by the [Code of Conduct](CODE_OF_CONDUCT.md)
+
+## General workflow
+
+Once a GitHub issue is accepted and assigned to you, please follow general workflow in order to submit your contribution:
+
+1. Fork the target repository under your GitHub username.
+2. Create a branch in your forked repository for the changes you are about to make.
+3. Commit your changes in the branch you created in step 2. All commits need to be signed-off. Check the [legal](#legal) section bellow for more details.
+4. Push your commits to your remote fork.
+5. Create a Pull Request from your remote fork pointing to the HEAD branch (usually `main` branch) of the target repository.
+6. Check the GitHub build and ensure that all checks are green.
+
+## Legal
+
+Procore projects use Developer Certificate of Origin ([DCO](https://GitHub.com/apps/dco/)).
+
+Please sign-off your contributions by doing ONE of the following:
+
+* Use `git commit -s ...` with each commit to add the sign-off or
+* Manually add a `Signed-off-by: Your Name <your.email@example.com>` to each commit message.
+
+The email address must match your primary GitHub email. You do NOT need cryptographic (e.g. gpg) signing.
+
+* Use `git commit -s --amend ...` to add a sign-off to the latest commit, if you forgot.
+
+*Note*: Some projects will provide specific configuration to ensure all commits are signed-off. Please check the project's documentation for more details.
+
+## Tests
+
+Make sure your changes are properly covered by automated tests. We aim to build an efficient test suite that is low cost to maintain and bring value to project. Prefer writing unit-tests over heavy end-to-end (e2e) tests. However, sometimes e2e tests are necessary. If you aren't sure, ask one of the maintainers about the requirements for your pull-request.

data/README.md

@@ -1,114 +1,147 @@
 # Handcuffs
 
-[![Circle CI](https://circleci.com/gh/procore/handcuffs.svg?style=svg)](https://circleci.com/gh/procore/handcuffs)
+[![Test](https://github.com/procore-oss/handcuffs/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/procore-oss/handcuffs/actions/workflows/test.yaml)
+[![Gem Version](https://badge.fury.io/rb/handcuffs.svg)](https://badge.fury.io/rb/handcuffs)
+[![Discord](https://img.shields.io/badge/Chat-EDEDED?logo=discord)](https://discord.gg/PbntEMmWws)
 
-Handcuffs provides an easy way to run migrations in phases in your [Ruby on
-Rails](https://rubyonrails.org/) application.
+Handcuffs provides an easy way to run [Ruby on Rails](https://rubyonrails.org/) migrations in phases using a simple process:
 
-To configure, first create a handcuff initializer and define a configuration
+1. Define a set of named phases in the order in which they should be run
+2. Tag migrations with one of the defined phase names
+3. Run migrations by phase at start, end or outside of application deployment
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'handcuffs'
+```
+
+And then execute:
+
+```bash
+bundle
+```
+
+Or install it directly on the current system using:
+
+```bash
+gem install handcuffs
+```
+
+## Usage
+
+### Configuration
+
+Create a handcuffs initializer and define the migration phases in the order in which they should be run. You should also define a default phase for pre-existing "untagged" migrations, or if you want the option to tag only custom phases.
+
+The most basic configuration is an array of phase names, and using the first one as the default:
 
 ```ruby
 # config/initializers/handcuffs.rb
 
 Handcuffs.configure do |config|
+  # pre_restart migrations will/must run before post_restart migrations
   config.phases = [:pre_restart, :post_restart]
+  config.default_phase = :pre_restart
 end
 ```
 
-Then call `phase` from inside your migrations
+If you have more complex or asynchrous workflows, you can use an alternate hash notation that allows prerequisite stages to be specified explicitly:
 
 ```ruby
-# db/migrate/20160318230933_add_on_sale_column.rb
+# config/initializers/handcuffs.rb
 
-class AddOnSaleColumn < ActiveRecord::Migration
+Handcuffs.configure do |config|
+  config.phases = {
+    # Prevent running post_restart migrations if there are outstanding
+    # pre_restart migrations
+    post_restart: [:pre_restart],
+    # Require pre_restarts before data_migrations, but do not enforce ordering
+    # between data_migrations and post_restarts
+    data_migrations: [:pre_restart],
+    # pre_restarts have no prerequisite phases
+    pre_restart: []
+  }
+end
+```
+The default phase order in this case is determined by [Tsort](https://github.com/ruby/tsort) (topological sort). In order to validate the configuration and expected phase order it is recommended that you check the phase configuration after any changes using the rake task:
+
+```ruby
+rake handcuffs:phase_order
+```
+
+This will display the default order in which phases will be run and list the prerequisites of each phase. It will raise an error if there are any circular dependencies or if any prerequisite is not a valid phase name.
+
+### Tagging Migrations
+
+Once configured, you can assign each migration to one of the defined phases using the `phase` setter method:
+
+```ruby
+# db/migrate/20240318230933_add_on_sale_column.rb
+
+class AddOnSaleColumn < ActiveRecord::Migration[7.0]
 
   phase :pre_restart
 
-  def up
+  def change
     add_column :products, :on_sale, :boolean
   end
-
-  def down
-    remove_column :products, :on_sale
-  end
-
 end
 ```
 
 ```ruby
-# db/migrate/20160318230988_add_on_sale_index
+# db/migrate/20240318230988_add_on_sale_index
 
-class AddOnSaleIndex < ActiveRecord::Migration
+class AddOnSaleIndex < ActiveRecord::Migration[7.0]
 
   phase :post_restart
 
-  def up
+  def change
     add_index :products, :on_sale, algorithm: :concurrently
   end
-
-  def down
-    remove_index :products, :on_sale
-  end
-
 end
 ```
+### Running Migrations In Phases
+
+After Handcuffs is configured and migrations are properly tagged, you can then run migrations in phases using the `handcuffs:migrate` rake task with the specific phase to be run:
 
-You can then run your migrations in phases using
 ```bash
 rake 'handcuffs:migrate[pre_restart]'
 ```
+
 or
+
 ```bash
 rake 'handcuffs:migrate[post_restart]'
 ```
 
-You can run all migrations using
-```bash
-rake 'handcuffs:migrate[all]'
-```
+*Note:* If you run phases out of order, or attempt to run a phase before outstanding migrations with a prerequisite phase have been run, a `HandcuffsPhaseOutOfOrderError` will be raised.
 
-This differs from running `rake db:migrate` in that migrations will be run in
-the _order that the phases are defined in the handcuffs config_.
+### Running All Migrations
 
-If you run a handcuffs rake task and any migration does not have a phase
-defined, an error will be raised before any migrations are run. To prevent this
-error, you can define a default phase for migrations that don't define one.
-```ruby
-# config/initializers/handcuffs.rb
+In CI and local developement you may want to run all phases at one time.
 
-Handcuffs.configure do |config|
-  config.phases = [:pre_restart, :post_restart]
-  config.default_phase = :pre_restart
-end
-```
-
-## Installation
-
-Add this line to your application's Gemfile:
+Handcuffs offers a single command that will run all migrations in phases and in the configured order:
 
-```ruby
-gem 'handcuffs'
+```bash
+rake 'handcuffs:migrate[all]'
 ```
 
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
+This differs from running `rake db:migrate` in that migrations will be run in batches corresponding to the _order that the phases are defined in the handcuffs config_. Again, you can use `rake handcuffs:phase_order` to preview the order ahead of time.
 
-    $ gem install handcuffs
+Of course, you can always run `rake db:migrate` at any time to run all migrations using the Rails default ordering and without regard to Handcuffs phase if you wish.
 
-## Running specs
+## Contributing
 
-The specs for handcuffs are in the dummy application at `/spec/dummy/spec`. The
-spec suite requires PostgreSQL. To run it you will have to set the environment
-variables `POSTGRES_DB_USERNAME` and `POSTGRES_DB_PASSWORD`. You can then run
-the suite using `rake spec`
+Bug reports and pull requests are welcome on GitHub at <https://github.com/procore-oss/handcuffs>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
-## Contributing
+## Running Tests Locally
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/procore/handcuffs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+The specs for handcuffs are in the dummy application at `/spec/dummy/spec`. The spec suite requires PostgreSQL. To run it you will have to set the environment variables `POSTGRES_DB_USERNAME` and `POSTGRES_DB_PASSWORD`.
 
+We use [appraisal](https://github.com/thoughtbot/appraisal) to run our test suite against all Rails versions that we support, as a means of quickly identifying potential regressions. To do this locally, first run `bundle exec appraisal install` to ensure all required dependencies are setup, and then run `bundle exec appraisal rspec`.
 
 ## License
 
@@ -117,8 +150,8 @@ The gem is available as open source under the terms of the [MIT License](http://
 ## About Procore
 
 <img
-  src="https://www.procore.com/images/procore_logo.png"
-  alt="Procore Logo"
+  src="https://raw.githubusercontent.com/procore-oss/.github/main/procorelightlogo.png"
+  alt="Procore Open Source"
   width="250px"
 />
 

data/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Supported Versions
+
+Ruby versions that are currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| <=2.7   | :x:                |
+| 3.0     | :white_check_mark: |
+| 3.1     | :white_check_mark: |
+| 3.2     | :white_check_mark: |
+| 3.3     | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+Please click the `Report a vulnerability` button [here](https://github.com/procore-oss/handcuffs/security) to report a vulnerability.
+
+A maintainer will respond to you as soon as possible and discuss the process to get the vulnerability fixed.

data/gemfiles/rails_6.1.gemfile

@@ -2,6 +2,6 @@
 
 source "https://rubygems.org"
 
-gem "rails", "~> 6.1"
+gem "rails", "~> 6.1.0"
 
 gemspec path: "../"

data/gemfiles/{rails_5.2.gemfile → rails_7.0.gemfile}

@@ -2,6 +2,6 @@
 
 source "https://rubygems.org"
 
-gem "rails", "~> 5.2.3"
+gem "rails", "~> 7.0.0"
 
 gemspec path: "../"

data/gemfiles/{rails_6.gemfile → rails_7.1.gemfile}

@@ -2,6 +2,6 @@
 
 source "https://rubygems.org"
 
-gem "rails", "~> 6.0.1"
+gem "rails", "~> 7.1.0"
 
 gemspec path: "../"

data/handcuffs.gemspec

@@ -6,18 +6,21 @@ require 'handcuffs/version'
 Gem::Specification.new do |spec|
   spec.name          = "handcuffs"
   spec.version       = Handcuffs::VERSION
-  spec.authors       = ["Brad Urani"]
-  spec.email         = ["bradurani@gmail.com", "opensource@procore.com"]
+  spec.authors       = ["Procore Technologies, Inc."]
+  spec.email         = ["opensource@procore.com"]
 
   spec.summary       = %q{A Ruby gem for running Active Record migrations in phases}
   spec.description   = %q{Allows you to define a phase on Active Record migrations and provides rake tasks for running only migrations tagged with a certain phase}
-  spec.homepage      = "https://github.com/procore/handcuffs/"
+  spec.homepage      = "https://github.com/procore-oss/handcuffs/"
   spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.0')
 
   # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
   # delete this section to allow pushing this gem to any host.
   if spec.respond_to?(:metadata)
     spec.metadata['allowed_push_host'] = "https://rubygems.org"
+    spec.metadata['rubygems_mfa_required'] = 'true'
+    spec.metadata['homepage_uri'] = spec.homepage
   else
     raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
   end
@@ -31,7 +34,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "pg"
   spec.add_development_dependency "pry"
   spec.add_development_dependency "pry-byebug"
-  spec.add_development_dependency "rspec-rails", "~> 3.0"
+  spec.add_development_dependency "rspec-rails", "~> 6.1"
+  spec.add_development_dependency "simplecov"
 
-  spec.add_runtime_dependency "rails", ">= 4.0"
+  spec.add_runtime_dependency "rails", ">= 6.1"
 end

data/lib/handcuffs/configuration.rb

@@ -10,7 +10,7 @@ module Handcuffs
   end
 
   class Configurator
-    attr_accessor :phases
+    attr_reader :phases
     attr_accessor :default_phase
 
     def initialize
@@ -18,7 +18,9 @@ module Handcuffs
       @default_phase = nil
     end
 
+    def phases=(phases)
+      @phases = Phases.new(phases)
+    end
   end
-
 end
 

data/lib/handcuffs/errors.rb

@@ -44,7 +44,7 @@
   class HandcuffsPhaseOutOfOrderError < HandcuffsError
     def initialize(not_run_phase, attempted_phase)
       msg = <<-MESSAGE
-        Your tried to run #{attempted_phase.to_s}, but #{not_run_phase.to_s} has not been run
+        You tried to run #{attempted_phase.to_s}, but #{not_run_phase.to_s} has not been run
       MESSAGE
       super msg
     end

data/lib/handcuffs/extensions.rb

@@ -1,12 +1,12 @@
+# frozen_string_literal: true
+
 module Handcuffs
+  # Extended by ActiveRecord::Migrator in order to track the current phase
   module Extensions
-
-    attr_reader :handcuffs_phase
+    attr_accessor :handcuffs_phase
 
     def phase(phase)
       @handcuffs_phase = phase
     end
-
   end
 end
-

data/lib/handcuffs/pending_filter_ext.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Handcuffs
+  # PendingFilter is prepended to ActiveRecord::Migrator in the rake tasks
+  # in order to check the current phase before it is run
+  module PendingFilterExt
+    def runnable
+      attempted_phase = self.class.handcuffs_phase
+      if @direction == :up
+        Handcuffs::PhaseFilter.new(attempted_phase, @direction).filter(super)
+      else
+        phase_migrations = Handcuffs::PhaseFilter.new(attempted_phase, @direction).filter(migrations)
+        runnable = phase_migrations[start..finish]
+        runnable.pop if target
+        runnable.find_all { |m| ran?(m) }
+      end
+    end
+  end
+end

data/lib/handcuffs/phase_filter.rb

@@ -41,7 +41,7 @@ class Handcuffs::PhaseFilter
   end
 
   def check_order_up!(by_phase, defined_phases)
-    defined_phases.take_while { |defined_phase| defined_phase != attempted_phase }
+    defined_phases.prereqs(attempted_phase)
       .detect { |defined_phase| by_phase.key?(defined_phase) }
       .tap do |defined_phase|
         raise HandcuffsPhaseOutOfOrderError.new(defined_phase, attempted_phase) if defined_phase
@@ -58,7 +58,7 @@ class Handcuffs::PhaseFilter
   end
 
   def all_phases_by_configuration_order(by_phase, defined_phases)
-    defined_phases.reduce([]) do |acc, phase|
+    defined_phases.in_order.reduce([]) do |acc, phase|
       acc | Array(by_phase[phase])
     end.map { |mh| mh[:proxy] }
   end

data/lib/handcuffs/phases.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'tsort'
+
+module Handcuffs
+  # Phases encapsulates the list of phases and any interdependencies
+  class Phases
+    def initialize(phases)
+      @phases = case phases
+                when Hash
+                  phases.each_with_object({}) do |phase, acc|
+                    acc[phase[0].to_sym] = Array(phase[1]).map(&:to_sym)
+                  end
+                else
+                  # Assume each entry depends on all entries before it
+                  phases.map(&:to_sym).each_with_object({}) do |phase, acc|
+                    acc[phase] = phases.take_while { |defined_phase| defined_phase != phase }
+                  end
+                end
+    end
+
+    def to_sentence
+      @phases.keys.to_sentence
+    end
+
+    def include?(phase)
+      @phases.include?(phase)
+    end
+
+    def in_order
+      TSort.tsort(
+        @phases.method(:each_key),
+        ->(phase, &block) { @phases.fetch(phase).each(&block) }
+      )
+    end
+
+    def prereqs(attempted_phase)
+      @phases.fetch(attempted_phase, [])
+    end
+  end
+end

data/lib/handcuffs/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Handcuffs
-  VERSION = "1.4.1"
+  VERSION = '2.1.0'
 end

data/lib/tasks/handcuffs.rake

@@ -1,56 +1,51 @@
+# frozen_string_literal: true
+
 namespace :handcuffs do
-  task :migrate, [:phase] => :environment do |t,args|
+  task :migrate, [:phase] => :environment do |_t, args|
     phase = setup(args, 'handcuffs:migrate')
     patch_migrator!(phase)
     run_task('db:migrate')
   end
 
-  task :rollback, [:phase] => :environment do |t,args|
+  task :rollback, [:phase] => :environment do |_t, args|
     phase = setup(args, 'handcuffs:rollback')
     patch_migrator!(phase)
     run_task('db:rollback')
   end
 
+  task phase_order: :environment do
+    raise HandcuffsNotConfiguredError unless Handcuffs.config
+
+    puts 'Configured Handcuffs phases, in order, are:'
+    phases = Handcuffs.config.phases || return
+
+    phases.in_order.each_with_index do |phase, idx|
+      puts (idx + 1).to_s.rjust(3) + ". #{phase}, requires: #{phases.prereqs(phase).join(', ').presence || '(nothing)'}"
+    end
+  end
+
   def setup(args, task)
-    phase = args.phase
+    phase = args.phase.presence&.to_sym
+
     raise RequiresPhaseArgumentError.new(task) unless phase.present?
-    raise HandcuffsNotConfiguredError.new unless Handcuffs.config
-    phase = phase.to_sym
-    unless Handcuffs.config.phases.include?(phase) || phase == :all
-      raise HandcuffsUnknownPhaseError.new(phase, Handcuffs.config.phases)
-    end
-    phase
+
+    raise HandcuffsNotConfiguredError unless Handcuffs.config
+
+    return phase if Handcuffs.config.phases.include?(phase) || phase == :all
+
+    raise HandcuffsUnknownPhaseError.new(phase, Handcuffs.config.phases)
   end
 
   def patch_migrator!(phase)
-    ActiveRecord::Migrator.prepend(PendingFilter)
-    ActiveRecord::Migrator.extend(PhaseAccessor)
+    ActiveRecord::Migrator.extend(Handcuffs::Extensions)
+    ActiveRecord::Migrator.prepend(Handcuffs::PendingFilterExt)
     ActiveRecord::Migrator.handcuffs_phase = phase
   end
 
   def run_task(name)
     Rake::Task.clear # necessary to avoid tasks being loaded several times in dev mode
-    Rails.application.load_tasks 
+    Rails.application.load_tasks
     Rake::Task[name].reenable # in case you're going to invoke the same task second time.
     Rake::Task[name].invoke
   end
-
-  module PendingFilter
-    def runnable
-      attempted_phase = self.class.handcuffs_phase
-      if(@direction == :up)
-        Handcuffs::PhaseFilter.new(attempted_phase, @direction).filter(super)
-      else
-        phase_migrations = Handcuffs::PhaseFilter.new(attempted_phase, @direction).filter(migrations)
-        runnable = phase_migrations[start..finish]
-        runnable.pop if target
-        runnable.find_all { |m| ran?(m) }
-      end
-    end
- end
-
-  module PhaseAccessor
-    attr_accessor :handcuffs_phase
-  end
-
 end