wagons 0.0.1 → 0.0.9

data/MIT-LICENSE

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

data/README.rdoc

@@ -1,21 +1,147 @@
-= Here be Wagons!
+= Here Be Wagons
 
-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.
+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
+As always, add this declaration to your application's Gemfile:
 
   gem 'wagons'
-  
-If you do not have one yet, create a .gemspec file for your application. This allows Rubygems to see your application as a (virtual) gem, so your wagons can define a dependency on it. As with all gems, move your (production) dependencies to this gemspec (+add_dependency+) and simply call +gemspec+ inside your Gemfile.
 
 Now you are ready for your first wagon. Generate it with
 
   rails generate wagon [name]
 
-== Under the hood
+This creates the structure of your wagon in <tt>vendor/wagons/[name]</tt>. In there, you find the file <tt>lib/[name]/wagon.rb</tt>,
+which defines the <tt>Rails::Engine</tt> 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 <tt>rake build</tt>. 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 <tt>lib/[wagon_name]/wagon.rb</tt>.
+
+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 <tt>require '[app_name]_[other_wagon]'</tt> on top of the 
+<tt>lib/[app_name]_[current_wagon].rb</tt> 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 an errors if one is not met. In <tt>lib/[wagon_name]/wagon.rb</tt> 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 <tt>db/fixtures[/environment]</tt>. 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 <tt>rake wagon:setup</tt> to run the migrations and load the seed data. Before you remove them 
+from +Wagonfile+, run <tt>rake wagon:remove WAGON=to_remove</tt> 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 
+<tt>db:migrate</tt>. 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, <tt>app:db:test:prepare</tt> 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 <tt>ruby -I test test/my_test.rb</tt> 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 <tt>test_helper.rb</tt> into your
+<tt>spec_helper.rb</tt>.
+
+=== 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 an own <tt>Gemfile.lock</tt> 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. <tt>rake wagon:bundle:update</tt> is here to help you exactly with that.
+We recommend to NOT check in the Wagon's <tt>Gemfile.lock</tt> 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 <tt>--deployment</tt> option cannot be used 
+with wagons. If you install your gems from <tt>vendor/cache</tt> into <tt>vendor/bundle</tt> 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.
+
 
-TODO:
-* Wagonfile
-* Rake Tasks
+{<img src="https://secure.travis-ci.org/codez/wagons.png" />}[http://travis-ci.org/codez/wagons]

data/Rakefile

@@ -21,16 +21,24 @@ RDoc::Task.new(:rdoc) do |rdoc|
 end
 
 
-
-
 Bundler::GemHelper.install_tasks
 
 require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.pattern = 'test/*_test.rb'
+  test.verbose = true
+end
 
 task :test do
-  puts "Testing wagons is a bit weird. So far, please run the following command directly in your shell:"
-  puts "(cd test/dummy/vendor/wagons/superliner && rake)"
+  begin
+    Bundler.with_clean_env { sh "cd test/dummy && rails g wagon test_wagon" }
+    Bundler.with_clean_env { sh "cd test/dummy && bundle exec rake db:migrate test  #{'-t' if Rake.application.options.trace}" }
+    Bundler.with_clean_env { sh "cd test/dummy && bundle exec rake wagon:test  #{'-t' if Rake.application.options.trace}" }
+  ensure
+    sh "rm -rf test/dummy/vendor/wagons/test_wagon"
+  end
 end
 
-
 task :default => :test
+

data/lib/generators/wagon/templates/%singular_name%.gemspec.tt

@@ -16,6 +16,4 @@ Gem::Specification.new do |s|
   s.files = Dir["{app,config,db,lib}/**/*"] + ["Rakefile"]
   s.test_files = Dir["test/**/*"]
 
-  s.add_dependency "<%= application_name %>"
-  
 end

data/lib/generators/wagon/templates/.gitignore

@@ -0,0 +1,5 @@
+.bundle/
+log/*.log
+pkg/
+doc/rdoc
+Gemfile.lock

data/lib/generators/wagon/templates/Gemfile.tt

@@ -7,14 +7,10 @@ source "http://rubygems.org"
 # development dependencies will be added by default to the :development group.
 gemspec
 
+# Load application Gemfile for all application dependencies.
+eval File.read(File.expand_path('Gemfile', ENV['APP_ROOT']))
+
 group :development, :test do
-  gem '<%= application_name %>', :path => ENV['APP_ROOT']
+  # Explicitly define the path for dependencies on other wagons.
+  # gem '<%= application_name %>_other_wagon', :path => "#{ENV['APP_ROOT']}/vendor/wagons"
 end
-
-# Declare any dependencies that are still in development here instead of in
-# your gemspec. These might include edge Rails or gems from your path or
-# Git. Remember to move these dependencies to your gemspec before releasing
-# your gem to rubygems.org.
-
-# To use debugger
-# gem 'ruby-debug'

data/lib/generators/wagon/templates/lib/%singular_name%/wagon.rb.tt

@@ -1,13 +1,16 @@
 module <%= class_name %>
   class Wagon < Rails::Engine
-    include ::Wagon
+    include Wagons::Wagon
     
-    # Add a load path for this specific Wagon
-    #config.autoload_paths += %W( #{config.root}/lib )
+    # Set the required application version.
+    app_requirement '>= 0'
+
+    # Add a load path for this specific wagon
+    # config.autoload_paths += %W( #{config.root}/lib )
 
     config.to_prepare do
       # extend application classes here
     end 
-  
+
   end
 end

data/lib/generators/wagon/wagon_generator.rb

@@ -1,4 +1,4 @@
-class WagonGenerator < Rails::Generators::NamedBase
+class WagonGenerator < Rails::Generators::NamedBase #:nodoc:
   
   attr_reader :wagon_name, :app_root_initializer
   
@@ -12,10 +12,29 @@ class WagonGenerator < Rails::Generators::NamedBase
     assign_names!("#{application_name}_#{name}")
   end
   
-  
   def copy_templates
-    self.destination_root = "vendor/wagons/#{wagon_name}" 
-    directory('.')
+    self.destination_root = "vendor/wagons/#{wagon_name}"
+    
+    # do this whole manual traversal to be able to replace every single file
+    # individually in the application.
+    all_templates.each do |file|
+      if File.basename(file) == '.empty_directory'
+        file = File.dirname(file)
+        directory(file, File.join(destination_root, file))
+      else
+        template(file, File.join(destination_root, file.sub(/\.tt$/, '')))
+      end
+    end
+  end
+  
+  private
+  
+  def all_templates
+    source_paths.collect do |path|
+      Dir[File.join(path, "**", "{*,.[a-z]*}")].
+          select {|f| File.file?(f) }.
+          collect {|f| f.sub(path + File::SEPARATOR, '') }
+    end.flatten.uniq.sort
   end
   
 end

data/lib/tasks/wagons.rake

@@ -1,3 +1,4 @@
+# The tasks available to the base application using wagons.
 
 namespace :wagon do
   desc "Run wagon migrations (options: VERSION=x, WAGON=abc, VERBOSE=false)"
@@ -22,7 +23,7 @@ namespace :wagon do
   end
   
   desc "Unseed wagon data (options: WAGON=abc)"
-  task :unseed => :abort_if_pending_migrations do
+  task :unseed do
     wagons.reverse.each { |wagon| wagon.unload_seed }
   end
   
@@ -30,14 +31,35 @@ namespace :wagon do
   task :setup => [:migrate, :seed]
   
   desc "Remove the specified wagon"
-  task :remove do
-    if wagons.size != 1
-      puts "Please specify a WAGON to remove"
-    elsif message = wagons.first.protect?
-      puts message
+  task :remove => :environment do
+    if wagons.size == 0 || (wagons.size > 1 && ENV['WAGON'].blank?)
+      puts "Please specify a WAGON to remove, or WAGON=ALL to remove all"
     else
-      Rake::Task['wagon:unseed'].invoke
-      Rake::Task['wagon:revert'].invoke
+      messages = wagons.collect {|w| w.protect? }.compact
+      if messages.present?
+        fail messages.join("\n")
+      else
+        Rake::Task['wagon:unseed'].invoke
+        Rake::Task['wagon:revert'].invoke
+      end
+    end
+  end
+  
+  desc "Generate an initializer to set the application version"
+  task :app_version do
+    file = Rails.root.join('config', 'initializers', 'wagon_app_version.rb')
+    unless File.exist?(file)
+      File.open(file, 'w') do |f|
+        f.puts <<FIN
+Wagons.app_version = '1.0.0'
+
+Wagons.all.each do |wagon|
+  unless wagon.app_requirement.satisfied_by?(Wagons.app_version)
+    raise "\#{wagon.gem_name} requires application version \#{wagon.app_requirement}; got \#{Wagons.app_version}"
+  end
+end
+FIN
+      end
     end
   end
   
@@ -72,23 +94,50 @@ eval(File.read(wagonfile)) if File.exist?(wagonfile)"
     end
   end
   
-  desc "list the loaded wagons"
+  namespace :file do
+    desc "Create a Wagonfile for production"
+    task :prod => :environment do
+      file = Rails.root.join('Wagonfile.prod')
+      File.open(file, 'w') do |f|
+        Wagons.all.each do |w|
+          f.puts "gem '#{w.gem_name}', '#{w.version}'"
+        end
+      end
+    end
+  end
+  
+  desc "List the loaded wagons"
   task :list => :environment do  # depend on environment to get correct order
     wagons.each {|p| puts p.wagon_name }
   end
   
-  namespace :test do
-    desc "Create script to test all wagons at once"
-    task :script => :environment do
-      script = 'vendor/wagons/test_wagons.sh'
-      File.open(script, 'w') do |f|
-        wagons.each do |w|
-          f.puts "(echo && echo '*** TESTING #{w.wagon_name.upcase} ***' && cd #{w.root.to_s[(Rails.root.to_s.size+1)..-1]} && bundle exec rake)"
-        end
+  desc "Run the tests of WAGON"
+  task :test do
+    ENV['CMD'] = "bundle exec rake #{'-t' if Rake.application.options.trace}"
+    Rake::Task['wagon:exec'].invoke
+  end
+  
+  desc "Execute CMD in WAGON's base directory"
+  task :exec do
+    wagons.each do |w|
+      puts "\n*** #{w.wagon_name.upcase} ***" if wagons.size > 1
+      rel_dir = w.root.to_s.sub(Rails.root.to_s + File::SEPARATOR, '')
+      cmd = "cd #{rel_dir} && #{ENV['CMD']}"
+      Bundler.with_clean_env do
+        verbose(false) { sh cmd }
       end
     end
   end
   
+  namespace :bundle do
+    desc "Run bundle update for all WAGONs"
+    task :update do
+      ENV['CMD'] = "bundle update --local"
+      Rake::Task['wagon:exec'].invoke
+    end
+  end
+  
+  
   # desc "Raises an error if there are pending wagon migrations"
   task :abort_if_pending_migrations => :environment do
     pending_migrations = ActiveRecord::Migrator.new(:up, wagons.collect(&:migrations_paths).flatten).pending_migrations
@@ -103,10 +152,60 @@ eval(File.read(wagonfile)) if File.exist?(wagonfile)"
   end
 end
 
+namespace :test do
+  desc "Test wagons (option WAGON=abc)"
+  task :wagons => 'wagon:test'
+end
+
+
+namespace :db do
+    namespace :seed do
+      desc "Load core and wagon seeds into the current environment's database."
+      task :all => ['db:seed', 'wagon:seed']
+    end
+    
+    namespace :setup do
+      desc "Create the database, load the schema, initialize with the seed data for core and wagons"
+      task :all => ['db:setup', 'wagon:setup']
+    end
+    
+    namespace :reset do
+      desc "Recreate the database, load the schema, initialize with the seed data for core and wagons"
+      task :all => ['db:reset', 'wagon:setup']
+    end
+    
+    # DB schema should not be dumped if wagon migrations are loaded
+    Rake::Task[:'db:_dump'].clear_actions
+
+    task :_dump do
+      migrator = ActiveRecord::Migrator.new(:up, ActiveRecord::Migrator.migrations_paths)
+      if migrator.migrated.size > migrator.migrations.size
+        puts "The database schema will not be dumped when there are loaded wagon migrations."
+        puts "To dump the application schema, please 'rake wagon:remove WAGON=ALL' wagons beforehand or reset the database."
+      else
+        Rake::Task[:'db:_dump_rails'].invoke
+      end
+      
+      Rake::Task[:'db:_dump'].reenable
+    end
+    
+    task :_dump_rails do
+      case ActiveRecord::Base.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}"
+      end
+      Rake::Task[:'db:_dump_rails'].reenable
+    end
+end
+
+
 # Load the wagons specified by WAGON or all available.
 def wagons
-  to_load = ENV['WAGON'].blank? ? :all : ENV['WAGON'].split(",").map(&:strip)
-  wagons = Wagon.all.select { |wagon| to_load == :all || to_load.include?(wagon.wagon_name) }
-  puts "Please specify at least one valid WAGON" if wagons.blank?
+  to_load = ENV['WAGON'].blank? || ENV['WAGON'] == 'ALL' ? :all : ENV['WAGON'].split(",").map(&:strip)
+  wagons = Wagons.all.select { |wagon| to_load == :all || to_load.include?(wagon.wagon_name) }
+  puts "Please specify at least one valid WAGON" if ENV['WAGON'].present? && wagons.blank?
   wagons
 end
+

data/lib/wagons/extensions/application.rb

@@ -0,0 +1,14 @@
+module Rails
+  class Application
+    protected
+
+    # Append wagons at the end of all railties, even after the application.
+    def ordered_railties
+      @ordered_railties ||= super.tap do |ordered|
+        Wagons.all.each do |w|
+          ordered.push(ordered.delete(w))
+        end
+      end
+    end
+  end
+end

data/lib/wagons/extensions/require_optional.rb

@@ -0,0 +1,9 @@
+class Object
+  # Requires the specified argument but silently ignores any LoadErrors.
+  def require_optional(*args)
+    require *args
+  rescue LoadError
+    # that's fine, it's an optional require
+  end
+  alias optional_require require_optional
+end

data/lib/wagons/{test_case.rb → extensions/test_case.rb}

@@ -1,4 +1,5 @@
-class ActiveSupport::TestCase
+module ActiveSupport #:nodoc:
+  class TestCase
   
     # Resets the fixtures to the new path
     def self.reset_fixture_path(path)
@@ -7,4 +8,6 @@ class ActiveSupport::TestCase
         self.fixture_path = path
         self.fixtures :all  
     end
+
+  end
 end