Improve development instructions and tooling (rename bin/rails, add bin/appraisal)

.rubocop.yml

@@ -23,6 +23,7 @@ AllCops:
     - vendor/**/*
     - scripts/**/*
     - gemfiles/**/*
+    - Brewfile
   NewCops: enable
 
 Layout/EmptyLineAfterMagicComment:

Brewfile

@@ -0,0 +1 @@
+brew "chromedriver"

CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# Contributing to GoodJob
+
+<!-- Please keep this section in sync with README.md#contribute -->
+
+All contributions, from feedback to code and beyond, are welcomed and appreciated 🙏
+
+- Review the [Prioritized Project Backlog](https://github.com/bensheldon/good_job/projects/1).
+- Open a new Issue or contribute to an [existing Issue](https://github.com/bensheldon/good_job/issues). Questions or suggestions are fantastic.
+- Participate according to our [Code of Conduct](/CODE_OF_CONDUCT.md).
+- Financially support the project via [Sponsorship](https://github.com/sponsors/bensheldon).
+
+For gem development and debugging information, please review the [README's Gem Development section](/README.md#gem-development).

README.md

@@ -60,6 +60,9 @@ For more of the story of GoodJob, read the [introductory blog post](https://isla
     - [CLI HTTP health check probes](#cli-http-health-check-probes)
 - [Contribute](#contribute)
     - [Gem development](#gem-development)
+        - [Development setup](#development-setup)
+        - [Rails development harness](#rails-development-harness)
+        - [Running tests](#running-tests)
     - [Release](#release)
 - [License](#license)
 
@@ -941,49 +944,82 @@ spec:
 
 ## Contribute
 
-Contributions are welcomed and appreciated 🙏
+<!-- Please keep this section in sync with CONTRIBUTING.md -->
+
+All contributions, from feedback to code and beyond, are welcomed and appreciated 🙏
 
 - Review the [Prioritized Project Backlog](https://github.com/bensheldon/good_job/projects/1).
 - Open a new Issue or contribute to an [existing Issue](https://github.com/bensheldon/good_job/issues). Questions or suggestions are fantastic.
-- Participate according to our [Code of Conduct](https://github.com/bensheldon/good_job/projects/1).
+- Participate according to our [Code of Conduct](/CODE_OF_CONDUCT.md).
+- Financially support the project via [Sponsorship](https://github.com/sponsors/bensheldon).
+
+For gem development and debugging information, please review the [README's Gem Development section](/README.md#gem-development).
 
 ### Gem development
 
-To run tests:
+#### Development setup
 
 ```bash
 # Clone the repository locally
-$ git clone [email protected]:bensheldon/good_job.git
+git clone [email protected]:bensheldon/good_job.git
 
 # Set up the local environment
-$ bin/setup
-
-# Run the tests
-$ bin/rspec
+bin/setup
 ```
 
-This gem uses Appraisal to run tests against multiple versions of Rails:
+#### Rails development harness
+
+A Rails application exists within `spec/test_app` that is used for development, test, and GoodJob Demo environments.
 
 ```bash
-# Install Appraisal(s) gemfiles
-$ bundle exec appraisal
+# Run a local development webserver
+bin/rails s
+
+# Disable job execution and cron for cleaner console output
+GOOD_JOB_ENABLE_CRON=0 GOOD_JOB_EXECUTION_MODE=external bin/rails s
 
-# Run tests
-$ bundle exec appraisal bin/rspec
+# Open the Rails console
+bin/rails c
 ```
 
 For developing locally within another Ruby on Rails project:
 
 ```bash
-# Within Ruby on Rails directory...
-$ bundle config local.good_job /path/to/local/git/repository
+# Within Ruby on Rails project directory
+# Ensure that the Gemfile is set to git with a branch e.g.
+# gem "good_job", git: "https://github.com/bensheldon/good_job.git", branch: "main"
+# Then, override the Bundle config to point to the local filesystem's good_job repository
+bundle config local.good_job /path/to/local/good_job/repository
 
 # Confirm that the local copy is used
-$ bundle install
+bundle install
 
 # => Using good_job 0.1.0 from https://github.com/bensheldon/good_job.git (at /Users/You/Projects/good_job@dc57fb0)
 ```
 
+#### Running tests
+
+Tests can be run against the primary development environment:
+
+```bash
+bin/rspec
+```
+
+Environment variables that may help with debugging:
+
+- `LOUD=1`: display all stdout/stderr output from all sources. This is helpful because GoodJob wraps some tests with `quiet { }` for cleaner test output, but it can hinder debugging.
+- `SHOW_BROWSER=1`: Run system tests headfully with Chrome/Chromedriver. Use `binding.irb` in the system tests to pause.
+
+Appraisal can be used to run a test matrix of multiple versions of Rails:
+
+```bash
+# Install Appraisal matrix of gemfiles
+bin/appraisal
+
+# Run tests against matrix
+bin/appraisal bin/rspec
+```
+
 ### Release
 
 Package maintainers can release this gem by running:

bin/appraisal

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+require 'bundler/setup'
+load Gem.bin_path('appraisal', 'appraisal')

bin/setup

@@ -10,10 +10,16 @@ def system!(*args)
 end
 
 FileUtils.chdir GEM_ROOT do
+  puts "\n== Installing gem dependencies =="
   system!('bundle install')
 end
 
 FileUtils.chdir APP_ROOT do
-  system!('bundle exec bin/rails db:setup')
-  system!('bundle exec bin/rails db:migrate')
+  puts "\n== Setting up database =="
+  system!('bin/rails db:setup')
+  system!('bin/rails db:test:prepare')
+  system!('bin/rails db:migrate')
 end
+
+puts "\n== Verifying system dependencies =="
+system("chromedriver -v") || abort("\n!!! Chrome/Chromedriver must be installed to run Rails System tests\n\n")

gemfiles/rails_6.0.gemfile

@@ -4,6 +4,7 @@ source "https://rubygems.org"
 
 gem "activerecord-jdbcpostgresql-adapter", platforms: [:jruby]
 gem "appraisal", branch: "fix-bundle-env", git: "https://github.com/bensheldon/appraisal.git"
+gem "matrix"
 gem "nokogiri", "~> 1.12.0"
 gem "pg", platforms: [:mri, :mingw, :x64_mingw]
 gem "rails", "~> 6.0.0"

gemfiles/rails_6.1.gemfile

@@ -4,6 +4,7 @@ source "https://rubygems.org"
 
 gem "activerecord-jdbcpostgresql-adapter", platforms: [:jruby]
 gem "appraisal", branch: "fix-bundle-env", git: "https://github.com/bensheldon/appraisal.git"
+gem "matrix"
 gem "nokogiri", "~> 1.12.0"
 gem "pg", platforms: [:mri, :mingw, :x64_mingw]
 gem "rails", "~> 6.1.0"

gemfiles/rails_7.0.gemfile

@@ -4,6 +4,7 @@ source "https://rubygems.org"
 
 gem "activerecord-jdbcpostgresql-adapter", platforms: [:jruby]
 gem "appraisal", branch: "fix-bundle-env", git: "https://github.com/bensheldon/appraisal.git"
+gem "matrix"
 gem "nokogiri", "~> 1.12.0"
 gem "pg", platforms: [:mri, :mingw, :x64_mingw]
 gem "rails", "~> 7.0.0"

spec/generators/good_job/install_generator_spec.rb

@@ -6,7 +6,7 @@
   around do |example|
     quiet { setup_example_app }
     example.run
-    remove_example_app
+    teardown_example_app
   end
 
   it 'creates a migration for good_jobs table' do

spec/support/example_app_helper.rb

@@ -5,6 +5,9 @@ module ExampleAppHelper
   def setup_example_app
     FileUtils.rm_rf(example_app_path)
 
+    # Rails will not install within a directory containing `bin/rails`
+    File.rename(Rails.root.join("../../bin/rails"), Rails.root.join("../../bin/_rails")) if File.exist?(Rails.root.join("../../bin/rails"))
+
     root_path = example_app_path.join('..')
     FileUtils.cd(root_path) do
       system("rails new #{app_name} -d postgresql --no-assets --skip-action-text --skip-action-mailer --skip-action-mailbox --skip-action-cable --skip-git --skip-sprockets --skip-listen --skip-javascript --skip-turbolinks --skip-system-test --skip-test-unit --skip-bootsnap --skip-spring --skip-active-storage")
@@ -18,6 +21,11 @@ def setup_example_app
     end
   end
 
+  def teardown_example_app
+    File.rename(Rails.root.join("../../bin/_rails"), Rails.root.join("../../bin/rails"))
+    FileUtils.rm_rf(example_app_path)
+  end
+
   def run_in_example_app(*args)
     FileUtils.cd(example_app_path) do
       system(*args) || raise("Command #{args} failed")
@@ -30,10 +38,6 @@ def run_in_test_app(*args)
     end
   end
 
-  def remove_example_app
-    FileUtils.rm_rf(example_app_path)
-  end
-
   def within_example_app
     # Will be running database migrations from the newly created Example App
     # but doing so in the existing database. This resets the database so that
@@ -53,9 +57,9 @@ def within_example_app
     end
 
     yield
-
+  ensure
     quiet do
-      remove_example_app
+      teardown_example_app
 
       tables.each do |table_name|
         ActiveRecord::Migration.drop_table(table_name) if ActiveRecord::Base.connection.table_exists?(table_name)
@@ -71,7 +75,7 @@ def example_app_path
   end
 
   def app_name
-    'test_app'
+    'example_app'
   end
 end