rails_drivers 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0d06c45078456d085945c12374a78a6e8cd8c5ae83ad7abc7fd55cda175e8c4
-  data.tar.gz: 18d5755774da8c851c0a39a25bcfa061445ac1acc06a98e27b22acb896443ab2
+  metadata.gz: 52e2b19b5bd5e3ef8921b6c64b08c03c9b1b4a568e70384ca1f855b9c140f783
+  data.tar.gz: 4429a66b2b8237e01a91447898b8a8a2a4efb88f5baa93382f594f0e48c7bcde
 SHA512:
-  metadata.gz: '09235347fa19b0da2ea6f20bebdfc4f2048c51760df3889575d7d6cd376a658ccac01a1053b03feaa7f6f89a329ca60db323aa2eb365b62977e29bd05e20a20c'
-  data.tar.gz: cff5ba12b81d820189e145f8b15535ec8ab42942963cb31eb501c359f4f2561171326d1cf93adab12df6d1a540f2f2465f4cb18c304316049561237409005656
+  metadata.gz: c1fec26f52e667e09aa237d232dd709b6f4011b48a222762c48b54d5bf19a33145f71d9c6ac3c39d8022b30da32e94042ce25772ed66707af650f91d8aff4b6e
+  data.tar.gz: '08e1af9dde001c22c9ca03bde90c6c10c14975797d6aa0588f08e98dedce155ab9704e9f1ebdb0b7942eced1e8d1b0f67afec230bdbe2458c2e13a23cf0c6803'

data/README.md

@@ -4,20 +4,32 @@
 
 Each driver is like a mini Rails app that has full access to the main app. A driver has its own `app`, `config`, `spec`, and `db` folder.
 
-Technically speaking, drivers are just a fancy name for putting code into a different folder. The advantage of doing this is that it provides clear-cut separation of concerns. If we follow a couple of simple rules, we can actually test that separation:
+Technically speaking, "driver" is just a fancy name for code that live in a different app folder. The advantage of doing this is that it provides clear-cut separation of concerns. If we follow a couple of simple rules, we can actually test that separation:
 
 - Drivers should not touch other drivers
 - The main app should not touch drivers directly
 
 The "main app" refers to the files inside your `<project root>/app` directory.
 
-If your test suite is good, you can test that these rules are adhered to by selectively adding and removing drivers before running your tests.
+If your test suite is good enough (see [Testing for coupling](#testing-for-coupling), you can test that these rules are adhered to by selectively adding and removing drivers before running your tests.
 
 ## Aren't these just engines?
 
 Very similar, yes. They use the same Rails facilities for adding new `app` paths, etc.
 
-But Drivers have less friction. They can be freely added and removed from your project without breaking anything. There's no need to mess around with gems, vendoring, or dummy apps.
+But practically speaking, drivers come with less friction. They can be freely added and removed from your project without making changes to the main app. There's no need to mess around with gems, routes, or dummy apps.
+
+Another difference is that drivers have a different dependency direction from engines. Engines are depended on by the Rails app:
+```
+         depends on
+(Rails App) --> (Engine)
+```
+A Rails app includes an engine as a plugin. The engine doesn't know how the Rails app works. For drivers, it's the other way around:
+```
+      depends on
+(Driver) --> (Rails App)
+```
+The Rails app doesn't know how its drivers work. It simply acts as a platform for all drivers to be built on. This makes drivers a great way to develop independent features that all rely on the same set of core functionality.
 
 ## Usage
 
@@ -25,14 +37,14 @@ Every folder inside `drivers` has its own `app`, `config`, `db`, and `spec` fold
 
 ### Creating a new driver
 
-Just run `rails g driver my_new_driver_name`.
+Run `rails g driver my_new_driver_name` to get a scaffold driver.
 
 ### Creating migrations for a driver
 
 `bundle exec driver my_driver_name generate migration blah etc_etc:string`
 
 The `driver` utility technically works with other generators and rake tasks, but is only guaranteed to work with migrations.
-The reason is that some generators assume a particular path, rather than using the Rails path methods.
+The reason is that some generators have hard-coded path strongs, rather than using the Rails path methods.
 
 ### Creating a rake task in a driver
 
@@ -49,6 +61,38 @@ end
 
 Can be executed using `rake driver:my_driver:my_namespace:task_name`.
 
+### Overrides
+
+Sometimes you want to add a method to a core class, but that method will only be used by one driver. This can be achieved by adding files to your driver's `overrides` directory.
+
+```ruby
+# app/models/product.rb
+# (doesn't have to be a model - can be anything)
+class Product < ApplicationRecord
+  # When you include this, every driver's product_override.rb is loaded and
+  # included. Works correctly with autoloading during development.
+  include RailsDrivers::Overrides
+end
+
+
+# drivers/my_driver/overrides/product_override.rb
+module MyDriver
+  module ProductOverride
+    extend ActiveSupport::Concern
+
+    def new_method
+      'Please only call me from code inside my_driver'
+    end
+  end
+end
+
+
+# Anywhere in my_driver (or elsewhere, but that's bad style)
+Product.new.new_method
+```
+
+For each Override, the accompanying class simply `includes` it, so any methods you define will be available throughout the whole app. To make sure your drivers don't change the core behavior of the app, see [Testing for coupling](#testing-for-coupling).
+
 ### Testing for coupling
 
 Since drivers are merged into your main application just like engines, there's nothing stopping them from accessing other drivers, and there's nothing stopping your main application from accessing drivers. In order to ensure those things don't happen, we have a handful of rake tasks:
@@ -74,11 +118,16 @@ rake driver:restore
 bundle exec driver admin do rspec --pattern '{spec,drivers/*/spec}/**{,/*/**}/*_spec.rb'
 # (can run with no drivers as well)
 bundle exec nodriver do rspec --pattern '{spec,drivers/*/spec}/**{,/*/**}/*_spec.rb'
+
+# Or you can move the driver folders around manually
+mv drivers/admin tmp/drivers/admin
+bundle exec rspec --pattern '{spec,drivers/*/spec}/**{,/*/**}/*_spec.rb'
+mv tmp/drivers/admin drivers/admin
 ```
 
 This lets you to ensure that the store and admin function properly without each other. Note we're running all of the main app's specs twice. This is good because we also want to make sure the main app is not reaching into drivers.
 
-Of course there's nothing stopping you from using if-statements to detect whether a driver is present. It's up to you to determine what's a "safe" level of crossover. Generally, if you find yourself using a lot of those if-statements, you should consider rethinking which functionality belongs in a driver and which functionality belongs in your main app.
+Of course there's nothing stopping you from using if-statements to detect whether a driver is present. It's up to you to determine what's a "safe" level of crossover. Generally, if you find yourself using a lot of those if-statements, you should consider rethinking which functionality belongs in a driver and which functionality belongs in your main app. On the other hand, the if-statements provide clear feature boundaries and can function as feature flags. Turning off a feature is as simple as removing a folder from `drivers`.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -92,7 +141,7 @@ And then execute:
 $ bundle install
 ```
 
-Add this line to your routes.rb:
+Finally, add these lines to your routes.rb:
 
 ```ruby
 require 'rails_drivers/routes'

data/lib/generators/driver/USAGE

@@ -11,5 +11,6 @@ Example:
         drivers/new_feature/app/models/new_feature
         drivers/new_feature/app/views/new_feature
         drivers/new_feature/config
+        drivers/new_feature/overrides
         drivers/new_feature/spec
         drivers/new_feature/lib

data/lib/generators/driver/driver_generator.rb

@@ -10,6 +10,7 @@ class DriverGenerator < Rails::Generators::NamedBase
     create_file "drivers/#{file_name}/spec/.keep", ''
     create_file "drivers/#{file_name}/db/migrate/.keep", ''
     create_file "drivers/#{file_name}/lib/tasks/.keep", ''
+    create_file "drivers/#{file_name}/overrides/.keep", ''
 
     template 'routes.rb.erb',      "drivers/#{file_name}/config/routes.rb"
     template 'initializer.rb.erb', "drivers/#{file_name}/config/initializers/#{file_name}_feature.rb"

data/lib/rails_drivers/overrides.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RailsDrivers
+  module Overrides
+    extend ActiveSupport::Concern
+
+    # Including this module results in all available override modules being
+    # included.
+    included do
+      cattr_reader :driver_overrides
+
+      possible_overrides = Dir.glob(
+        Rails.root.join(
+          'drivers', '*', 'overrides',
+          "#{name.underscore}_override.rb"
+        )
+      )
+
+      @@driver_overrides = possible_overrides.map do |path|
+        require_dependency path
+        %r{drivers/(?<driver_name>[^/]+)/overrides} =~ path
+
+        override = "#{driver_name.classify}::#{name}Override".constantize
+        include override
+        override
+      end.freeze
+
+      singleton_class.prepend CheckForShadowedMethods
+    end
+
+    # This module is prepended to the singleton class of the including class
+    # to detect when an override is attempting to re-define any methods.
+    module CheckForShadowedMethods
+      def method_added(method_name)
+        driver_overrides.each do |override|
+          next unless override.instance_methods.include?(method_name)
+
+          Rails.logger.warn "Driver override method #{override.name}##{method_name} "\
+            "is shadowed by #{name}##{method_name} and will likely not do anything."
+        end
+
+        super(method_name)
+      end
+    end
+  end
+end

data/lib/rails_drivers/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsDrivers
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/rails_drivers.rb

@@ -3,6 +3,7 @@
 require 'rails_drivers/version'
 require 'rails_drivers/setup'
 require 'rails_drivers/railtie'
+require 'rails_drivers/overrides'
 
 module RailsDrivers
   class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_drivers
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Nigel Baillie
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-14 00:00:00.000000000 Z
+date: 2020-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -102,6 +102,7 @@ files:
 - lib/generators/driver/templates/routes.rb.erb
 - lib/rails_drivers.rb
 - lib/rails_drivers/files.rb
+- lib/rails_drivers/overrides.rb
 - lib/rails_drivers/railtie.rb
 - lib/rails_drivers/routes.rb
 - lib/rails_drivers/setup.rb