wagons 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d06295f19bd1963830bd47006676c4b25eb2b1e7b30af0f8c2302996b129493
-  data.tar.gz: d3c66601cc2869001432ae9877cbd03dfd6a68f9685aa47ab929a3b36023dcef
+  metadata.gz: 115a339a7bcdac6dcaa1421a9c10b721ccbe58274b02fd88913c9a0c6c012bc1
+  data.tar.gz: 8b75fa6188d5742edc1468d07b07ecc9b7c4464c4f42eb52f4a12bf30af24c4c
 SHA512:
-  metadata.gz: bb293faaa5f7639c22dea5b78a98b202936ad6dd5fe6016c7215b81866861c9eb23a81a733e2dffc27ce09d1ebd7459f000a33dd73913e94633a4d0b96ad245a
-  data.tar.gz: ac080f11d0a70f91755e510f365a9c36bfec28e2918fd167edf58524f40834c52b0fae01bcb8dd44b1e1bce8ca7abc50bd96e877220ffbd454b80a9e4aaac076
+  metadata.gz: bb5f39ce863e8540db973fcb4882b35e8e3734edc380e58df0b72ed9da53412081b94389782ac6dccb431b204f400470bb88aeabecea37644e49b78f8acd71e0
+  data.tar.gz: 1f6330feb1ceaf5bf001c126a95dd661432e4ac96cf170031e26db94da183a3955406adc0491d65ce480057c2137c58bdf5971e0608ed8e62d1c9bc856a1bdde

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2012 Pascal Zumkehr
+Copyright 2012-2023 Pascal Zumkehr, Puzzle ITC
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,143 @@
+# Here Be Wagons
+
+[![Build Status](https://github.com/codez/wagons/actions/workflows/build.yml/badge.svg)](https://github.com/codez/wagons/actions/workflows/build.yml)
+[![Code Climate](https://api.codeclimate.com/v1/badges/32a0d860544681cf718c/maintainability)](https://codeclimate.com/github/codez/wagons/maintainability)
+
+Wagons are extensions to your application train running on Rails. You can see them as plugins that
+extend the behavior of your specific Rails application. This framework makes it easy to create and
+manage them.
+
+First of all, wagons are basically [Rails Engines](http://api.rubyonrails.org/classes/Rails/Engine.html),
+so make sure you are familiar with them. Wagons provide a handful of additions so your wagon
+engines actually know your application.
+
+Wagons differ from engines in a few points:
+
+- Wagons extend your application, engines extend Rails.
+- Wagon migrations are kept separately from your application's migrations to enable easy addition and removal of wagons.
+- When developing and testing, wagons use the main application instead of a dummy application.
+
+## Setup
+
+As always, add this declaration to your application's Gemfile:
+
+    gem 'wagons'
+
+Now you are ready for your first wagon. Generate it with
+
+    rails generate wagon [name]
+
+This creates the structure of your wagon in `vendor/wagons/[name]`. In there, you find the file `lib/[name]/wagon.rb`,
+which defines the `Rails::Engine` and includes the `Wagon` module. Here, you may also extend your application
+classes in a `config.to_prepare` block.
+
+In order to load wagons with the application, an entry in the `Gemfile` would be sufficient.
+To keep things flexible, wagons come with an additional file `Wagonfile`. Generate one for development purposes with:
+
+    rake wagon:file
+
+This will include all wagons found in `vendor/wagons` in development mode.
+Do not check `Wagonfile` into source control. In your deployments, you might want to have different entries in there.
+
+Once your wagon is ready to ship, a gem can be built with `rake build`. The name of a wagon gem must always start
+with the application name, followed with an underscore and the actual name of the wagon. In production, you may
+simply install the wagon gem and explicitly add a declaration to your `Wagonfile`.
+
+If your wagon contains migrations and probably seed data, update your database with
+
+    rake wagon:setup WAGON=[name]
+
+Leave off the `WAGON` parameter to setup all wagons in your `Wagonfile`. This should not interfere with wagons that are
+already set up. Migrations are only run if they are not loaded yet, as usual.
+
+## Extending your application with a wagon
+
+Ruby and Rails provide all the magic required to extend your application from within a wagon.
+
+To add new models, controllers or views, simply create them in the `app` directory of your wagon, as you would in a regular engine.
+
+To extend existing models and controllers, you may create modules with the required functionality.
+Include them into your application classes in a `config.to_prepare` block in `lib/[wagon_name]/wagon.rb`.
+
+To extend views, wagons provides a simple view helper that looks for partials in all view paths. Any template that
+might be extended by a wagon can include a call like this:
+
+    <%= render_extensions :details %>
+
+Any partials living in an equally named subfolder as the calling template and starting with the given key are rendered at this place.
+
+## Wagon dependencies
+
+Wagons may depend on each other and/or have certain requirements on their load order. To make sure something
+is loaded before the current wagon, add a `require '[app_name]_[other_wagon]'` on top of the
+`lib/[app_name]_[current_wagon].rb` file. For development dependencies, there is an extra `require_optional`
+method that will not raise a `LoadError` if the dependency is not found.
+
+To control that the main application actually supports a certain wagon, an application version may be defined
+so wagons can define a requirement. The application version can be set in an initializer. Create it with:
+
+    rake wagon:app_version
+
+Besides setting the version, this initializer will check all loaded wagons for their application requirement
+and raise errors if one is not met. In `lib/[wagon_name]/wagon.rb` the requirement may be defined, e.g.:
+
+    app_requirement '>= 1.0'
+
+The syntax follows the Ruby gem version and requirements.
+
+## Seed Data
+
+Wagons integrates [Seed Fu](https://github.com/mbleigh/seed-fu) for seed data. All seed data from the application
+is also available in wagon tests, as long as no fixture files overwrite the corresponding tables.
+
+Wagons may come with their own seed data as well. Simply put it into `db/fixtures[/environment]`. To allow for
+an automatic removal of wagons, [Seed Fu-ndo](https://github.com/codez/seed-fu-ndo) is able to record
+seed file instructions and destroy all entries that exist in the database. Just make sure that you only use
+the `seed` and `seed_once` methods in these files, or the unseed may not work correctly.
+
+## Beware
+
+There are a few other things that work differently with wagons:
+
+### Schema & Migrations
+
+Wagons are extensions to your application that may vary between various installations. Wagon tables are added
+and removed as wagons are installed or uninstalled. After you have added a wagon's gem to your production
+`Wagonfile`, run `rake wagon:setup` to run the migrations and load the seed data. Before you remove them
+from `Wagonfile`, run `rake wagon:remove WAGON=to_remove` to eliminate the artifacts from the database first.
+
+In this way, the `schema.rb` file must only contain the tables of the application, not of all wagons.
+When you have migrations for your main application and wagons loaded, the schema will not be dumped on
+`db:migrate`. You need to either remove the wagons or reset the database before the schema may be dumped.
+This is (currently) the cost for having arbitrary pluggable application extensions.
+
+### Tests
+
+Wagons use your application for tests. This is also true for your application's test database. To get the
+correct setup, `app:db:test:prepare` is extended to run the migration of the current wagon and all its
+dependencies, as well as their seed data. Once the database is set up, single tests may be run with
+the usual `ruby -I test test/my_test.rb` command.
+
+The `test_helper.rb` of the main application is included in all wagon tests. Any additions in
+this file are available in wagon tests as well. The only thing wagons need to do is reseting the
+fixture path to the wagon's test fixtures.
+
+RSpec works fine with wagons as well. Simply put the heading lines found in `test_helper.rb` into your
+`spec_helper.rb`.
+
+### Gem Bundling
+
+Bundler manages application dependencies, with a stress on application. Because wagons live
+inside your application during development, the app's `Gemfile` is included in each wagon's `Gemfile`.
+However, Bundler still keeps a separate `Gemfile.lock` for each wagon, so you have to make sure to keep
+these up to date when you change your main application gems. The gem versions for the wagons should be
+the same as for the application. `rake wagon:bundle:update` is here to help you exactly with that.
+We recommend to NOT check in the Wagon's `Gemfile.lock` file into source control.
+
+Unfortunately, adding wagon gems to the `Wagonfile` in production also breaks with Bundler's approach
+of locking down application gems. Because of that, the `--deployment` option cannot be used
+with wagons. If you install your gems from `vendor/cache` into `vendor/bundle` or so,
+you still get most of the benefits of using Bundler, including the guarantee for the very same gem
+versions as used in development.
+
+Contributions to this or any other issues are very welcome.

data/lib/tasks/wagons.rake

@@ -143,14 +143,12 @@ eval(File.read(wagonfile)) if File.exist?(wagonfile)"
   task :abort_if_pending_migrations => :environment do
     paths = wagons.collect(&:migrations_paths).flatten
 
-    pending_migrations =
-      if Gem::Version.new(Rails::VERSION::STRING) < Gem::Version.new('6.0.0')
-        context = ActiveRecord::MigrationContext.new(paths)
-        ActiveRecord::Migrator.new(:up, context.migrations).pending_migrations
-      else
-        context = ActiveRecord::MigrationContext.new(paths, ActiveRecord::SchemaMigration)
-        ActiveRecord::Migrator.new(:up, context.migrations, ActiveRecord::SchemaMigration).pending_migrations
-      end
+    context = ActiveRecord::MigrationContext.new(paths, ActiveRecord::SchemaMigration)
+    pending_migrations = ActiveRecord::Migrator.new(
+      :up,
+      context.migrations,
+      ActiveRecord::SchemaMigration
+    ).pending_migrations
 
     if pending_migrations.any?
       puts "You have #{pending_migrations.size} pending migrations:"
@@ -188,12 +186,7 @@ namespace :db do
     Rake::Task[:'db:_dump'].clear_actions
 
     task :_dump do
-      context =
-        if Gem::Version.new(Rails::VERSION::STRING) < Gem::Version.new('6.0.0')
-          ActiveRecord::MigrationContext.new(ActiveRecord::Migrator.migrations_paths)
-        else
-          ActiveRecord::MigrationContext.new(ActiveRecord::Migrator.migrations_paths, ActiveRecord::SchemaMigration)
-        end
+      context = ActiveRecord::MigrationContext.new(ActiveRecord::Migrator.migrations_paths, ActiveRecord::SchemaMigration)
       migrated = Set.new(context.get_all_versions)
       if migrated.size > context.migrations.size
         puts "The database schema will not be dumped when there are loaded wagon migrations."
@@ -206,11 +199,15 @@ namespace :db do
     end
 
     task :_dump_rails do
-      case ActiveRecord::Base.schema_format
+      schema_format =
+        Gem::Version.new(Rails::VERSION::STRING) < Gem::Version.new('7.1.0') ?
+        ActiveRecord::Base.schema_format : ActiveRecord.schema_format
+
+      case schema_format
       when :ruby then Rake::Task["db:schema:dump"].invoke
       when :sql  then Rake::Task["db:structure:dump"].invoke
       else
-        raise "unknown schema format #{ActiveRecord::Base.schema_format}"
+        raise "unknown schema format #{schema_format}"
       end
       Rake::Task[:'db:_dump_rails'].reenable
     end

data/lib/wagons/extensions/migration.rb

@@ -19,16 +19,15 @@ module ActiveRecord
       private
 
       def load_wagon_schema!
-        Base.clear_all_connections!
+        if rails_version_smaller_than('7.1.0')
+          Base.clear_all_connections!
+        else
+          Base.connection_handler.clear_all_connections!
+        end
 
         # Contrary to the original rails approach (#load_schema_if_pending!),
         # purge the database first to get rid of all wagon tables.
-        config =
-          if Gem::Version.new(Rails::VERSION::STRING) < Gem::Version.new('6.1.0')
-            Base.configurations['test']
-          else
-            Base.configurations.configs_for(env_name: 'test').first
-          end
+        config = Base.configurations.configs_for(env_name: 'test').first
         Tasks::DatabaseTasks.purge(config)
 
         Base.establish_connection(config)
@@ -39,7 +38,11 @@ module ActiveRecord
 
       def load_app_schema(config)
         Tasks::DatabaseTasks.load_schema(config)
-        check_pending!
+        if rails_version_smaller_than('7.1.0')
+          check_pending!
+        else
+          check_all_pending!
+        end
       end
 
       def app_needs_migration?
@@ -52,29 +55,41 @@ module ActiveRecord
       end
 
       def migration_versions_in_db
-        if Base.connection.table_exists?(SchemaMigration.table_name)
+        if schema_migration_table_exists?
           migration_context.get_all_versions.to_set
         else
           [].to_set
         end
       end
 
-      def migration_context
-        if Gem::Version.new(Rails::VERSION::STRING) < Gem::Version.new('6.0.0')
-          MigrationContext.new(Migrator.migrations_paths)
+      def schema_migration_table_exists?
+        if rails_version_smaller_than('7.1.0')
+          Base.connection.table_exists?(SchemaMigration.table_name)
         else
+          SchemaMigration.new(Base.connection).table_exists?
+        end
+      end
+
+      def migration_context
+        if rails_version_smaller_than('7.1.0')
           MigrationContext.new(Migrator.migrations_paths, SchemaMigration)
+        else
+          MigrationContext.new(Migrator.migrations_paths)
         end
       end
 
       def maintain_test_schema?
-        if Gem::Version.new(Rails::VERSION::STRING) < Gem::Version.new('7.0.0')
+        if rails_version_smaller_than('7.0.0')
           ActiveRecord::Base.maintain_test_schema
         else
           ActiveRecord.maintain_test_schema
         end
       end
 
+      def rails_version_smaller_than(version)
+        Gem::Version.new(Rails::VERSION::STRING) < Gem::Version.new(version)
+      end
+
     end
   end
 end

data/lib/wagons/extensions/test_case.rb

@@ -4,7 +4,11 @@ module ActiveSupport #:nodoc:
     def self.reset_fixture_path(path)
       self.fixture_table_names = []
       self.fixture_class_names = {}
-      self.fixture_path = path
+      if Gem::Version.new(Rails::VERSION::STRING) < Gem::Version.new('7.1.0')
+        self.fixture_path = path
+      else
+        self.fixture_paths = [path]
+      end
       fixtures :all
     end
   end

data/lib/wagons/version.rb

@@ -1,3 +1,3 @@
 module Wagons
-  VERSION = '0.7.0'
+  VERSION = '0.8.0'
 end

data/lib/wagons/wagon.rb

@@ -127,10 +127,10 @@ module Wagons
     end
 
     def migration_context
-      if Gem::Version.new(Rails::VERSION::STRING) < Gem::Version.new('6.0.0')
-        ActiveRecord::MigrationContext.new(migrations_paths)
-      else
+      if Gem::Version.new(Rails::VERSION::STRING) < Gem::Version.new('7.1.0')
         ActiveRecord::MigrationContext.new(migrations_paths, ActiveRecord::SchemaMigration)
+      else
+        ActiveRecord::MigrationContext.new(migrations_paths)
       end
     end
 

data/test/ci/{rails60.gemfile → rails70.gemfile}

@@ -2,7 +2,7 @@ source 'https://rubygems.org'
 
 gemspec :path => '../..'
 
-gem 'rails', '~> 6.0.0'
+gem 'rails', '~> 7.0.0'
 
 group :test do
   gem 'mocha', :require => false

data/test/dummy/Gemfile

@@ -6,7 +6,7 @@ gem 'wagons', :path => File.expand_path(__FILE__).split("test#{File::SEPARATOR}d
 
 group :development, :test do
   gem 'net-smtp'
-  gem 'sqlite3'
+  gem 'sqlite3', '~> 1.4'
 end
 
 group :test do