maintenance_job 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f87c4d865f2b160eb5e14f814c45d19a5228246695ce1e42677ed294c2f0d5c4
+  data.tar.gz: dc71e1078490b57e46eda10f13d8d58e2466f8b70fc93675cf6ad746d2bef85e
+SHA512:
+  metadata.gz: 910e40a0a7d79b6167d5eb59c856aff58ad07abf1cdc6efb033eff5237b3bdc5fdcc7adf19023dc9796758215922f78583f8360e843b22a94080ceb3074054c9
+  data.tar.gz: 62f529f6e5701f7488696e51734211e5dff69472a38ea844f52f88d5410bfaf2d9955b51513f599d81f0acb02712e107cbad9c29ab2a959a5ac03ac76491226b

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright 2021 Ayush Newatia
+
+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

@@ -0,0 +1,67 @@
+# MaintenanceJob
+
+[![Tests](https://github.com/ayushn21/maintenance_job/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/ayushn21/maintenance_job/actions/workflows/tests.yml)
+[![Gem Version](https://badge.fury.io/rb/maintenance_job.svg)](https://badge.fury.io/rb/maintenance_job)
+
+`MaintenanceJob` is a mechanism to run testable one-off jobs at deploy time to manipulate data in the database.
+
+Theoretically this could be done in database migrations or rake tasks, but that's a terrible idea because the changes can't be tested. In the case of rake tasks, it would also require access to the prod environment to run the tasks which is not always feasible.
+
+This gem was heavily inspired by [this RailsConf 2020 talk](https://railsconf.org/2020/2020/video/alec-clarke-measure-twice-cut-once) by [@alecclarke](https://github.com/alecclarke).
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'maintenance_job'
+```
+
+And then execute:
+
+```bash
+$ bundle install && bin/rails maintenance_job:install
+```
+
+This will copy the database migration that tracks which maintenance jobs have been run and create a directory under `app/jobs` for all your maintenance jobs.
+
+## Usage
+
+### Run maintenance jobs on deploy
+
+Add `bin/rails maintenance_job:execute_pending_jobs` to your deploy script right after you run the database migrations.
+
+### Creating a maintenance job
+
+To create a new maintenance job, run:
+
+```bash
+$ bin/rails generate maintenance_job job_to_be_done
+```
+
+This will create two files:
+
+- `app/jobs/maintenance/job_to_be_done_job.rb`
+- `test/jobs/maintenance/job_to_be_done_job_test.rb`
+
+Implement your data manipulation, write some tests for it and deploy!
+
+### Ensuring all jobs have been run in local environments
+
+If you'd like to ensure any pending maintenance jobs have been run in the development environment, add the following line to your `ApplicationController`:
+
+`include MaintenanceJob::EnsureNoPendingJobs if Rails.env.development?`
+
+If there are any pending jobs in development, the developer will see an actionable error in the browser where they can run the pending jobs and continue.
+
+## Contributing
+
+1. Fork it (https://github.com/ayushn21/maintenance_job/fork)
+2. Clone the fork using `git clone` to your local development machine.
+3. Create your feature branch (`git checkout -b my-new-feature`)
+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
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,18 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/controllers/concerns/maintenance_job/ensure_no_pending_jobs.rb

@@ -0,0 +1,13 @@
+module MaintenanceJob
+  module EnsureNoPendingJobs
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :ensure_no_pending_maintenance_jobs
+    end
+
+    def ensure_no_pending_maintenance_jobs
+      raise MaintenanceJob::PendingJobsError if MaintenanceJob::Base.pending_jobs.present?
+    end
+  end
+end

data/app/errors/maintenance_job/pending_jobs_error.rb

@@ -0,0 +1,9 @@
+module MaintenanceJob
+  class PendingJobsError < StandardError
+    include ActiveSupport::ActionableError
+
+    action "Run pending maintenance jobs" do
+      MaintenanceJob::Base.run_pending_jobs
+    end
+  end
+end

data/app/jobs/maintenance_job/base.rb

@@ -0,0 +1,33 @@
+module MaintenanceJob
+  class Base < ActiveJob::Base
+    queue_as :default
+    discard_on ActiveRecord::RecordNotUnique
+    discard_on ActiveJob::DeserializationError
+
+    before_perform { self.class.record_run }
+
+    def perform
+      raise NotImplementedError
+    end
+
+    def self.record_run
+      Run.create(identifier: identifier)
+    end
+
+    def self.runnable?
+      Run.find_by(identifier: identifier).nil?
+    end
+
+    def self.pending_jobs
+      descendants.select(&:runnable?)
+    end
+
+    def self.run_pending_jobs
+      pending_jobs.each(&:perform_now)
+    end
+
+    def self.identifier
+      raise NotImplementedError
+    end
+  end
+end

data/app/models/maintenance_job/run.rb

@@ -0,0 +1,4 @@
+module MaintenanceJob
+  class Run < ActiveRecord::Base
+  end
+end

data/db/migrate/20210903143918_create_maintenance_job_runs.rb

@@ -0,0 +1,5 @@
+class CreateMaintenanceJobRuns < ActiveRecord::Migration[6.1]
+  def change
+    create_table :maintenance_job_runs, id: :string, primary_key: :identifier
+  end
+end

data/lib/generators/USAGE

@@ -0,0 +1,10 @@
+Description:
+    Generates a MaintenanceJob and corresponding test case to run one off
+    tasks at deploy time.
+
+Example:
+    bin/rails generate maintenance_job PopulateSomeNewColumn
+
+    This will create:
+        app/jobs/maintenance/populate_some_new_column_job.rb
+        test/jobs/maintenance/populate_some_new_column_job_test.rb

data/lib/generators/maintenance_job_generator.rb

@@ -0,0 +1,8 @@
+class MaintenanceJobGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path('templates', __dir__)
+
+  def generate_job_files
+    template "maintenance_job.rb.erb", "app/jobs/maintenance/#{file_name}_job.rb"
+    template "maintenance_job_test.rb.erb", "test/jobs/maintenance/#{file_name}_job_test.rb"
+  end
+end

data/lib/generators/templates/maintenance_job.rb.erb

@@ -0,0 +1,9 @@
+class Maintenance::<%= class_name %>Job < MaintenanceJob::Base
+  def perform
+    # Implement your fix here
+  end
+
+  def self.identifier
+    <%= Time.now.strftime("%Y%m%d%H%M%S").inspect %>
+  end
+end

data/lib/generators/templates/maintenance_job_test.rb.erb

@@ -0,0 +1,7 @@
+require "test_helper"
+
+class Maintenance::<%= class_name %>JobTest < ActiveJob::TestCase
+  test "it fixes things" do
+    assert false, "ensure the maintenance fix is tested!"
+  end
+end

data/lib/maintenance_job/engine.rb

@@ -0,0 +1,16 @@
+module MaintenanceJob
+  class Engine < ::Rails::Engine
+    isolate_namespace MaintenanceJob
+
+    initializer "maintenance_job.eager_load_namespace" do
+      autoloader = Rails.autoloaders.main
+      if autoloader.respond_to?(:on_setup)
+        autoloader.on_setup do
+          Maintenance.constants(false).each { |cname| Maintenance.const_get(cname) }
+        end
+      else
+        autoloader.preload(Rails.root.join("app", "jobs", "maintenance"))
+      end
+    end
+  end
+end

data/lib/maintenance_job/version.rb

@@ -0,0 +1,3 @@
+module MaintenanceJob
+  VERSION = '1.0.0'
+end

data/lib/maintenance_job.rb

@@ -0,0 +1,5 @@
+require "maintenance_job/version"
+require "maintenance_job/engine"
+
+module MaintenanceJob
+end

data/lib/tasks/maintenance_job_tasks.rake

@@ -0,0 +1,16 @@
+namespace :maintenance_job do
+  desc "Install the database migrations and file skeleton required for MaintenanceJob"
+  task :install do
+    Dir.mkdir(Rails.root.join("app", "jobs", "maintenance"))
+    File.write(Rails.root.join("app", "jobs", "maintenance", ".keep"), "")
+    File.write(Rails.root.join("app", "jobs", "maintenance.rb"), "module Maintenance; end")
+    puts "Created Maintenance module in Jobs directory"
+
+    Rake::Task["maintenance_job:install:migrations"].execute
+  end
+
+  desc "Runs all pending maintenance jobs"
+  task :execute_pending_jobs => :environment do
+    MaintenanceJob::Base.run_pending_jobs
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: maintenance_job
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ayush Newatia
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-10-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description:
+email:
+- ayush@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- Rakefile
+- app/controllers/concerns/maintenance_job/ensure_no_pending_jobs.rb
+- app/errors/maintenance_job/pending_jobs_error.rb
+- app/jobs/maintenance_job/base.rb
+- app/models/maintenance_job/run.rb
+- db/migrate/20210903143918_create_maintenance_job_runs.rb
+- lib/generators/USAGE
+- lib/generators/maintenance_job_generator.rb
+- lib/generators/templates/maintenance_job.rb.erb
+- lib/generators/templates/maintenance_job_test.rb.erb
+- lib/maintenance_job.rb
+- lib/maintenance_job/engine.rb
+- lib/maintenance_job/version.rb
+- lib/tasks/maintenance_job_tasks.rake
+homepage: https://github.com/ayushn21/maintenance_job
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/ayushn21/maintenance_job
+  source_code_uri: https://github.com/ayushn21/maintenance_job
+  changelog_uri: https://github.com/ayushn21/maintenance_job/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: Mechanism to run testable one-off jobs at deploy time to manipulate data
+test_files: []