README.textile in combustion-0.1.1 vs README.textile in combustion-0.2.0

@@ -1,7 +1,128 @@
 h1. Combustion
 
-More information/documentation coming soon.
+Combustion is a library to help you test your Rails Engines in a simple and effective manner, instead of creating a full Rails application in your spec or test folder.
 
+It allows you to write your specs within the context of your engine, using only the parts of a Rails app you need.
+
+h2. Usage
+
+Get the gem into either your gemspec or your Gemfile, depending on how you manage your engine's dependencies:
+
+<pre><code># gemspec
+gem.add_development_dependency 'combustion', '~> 0.2.0'
+# Gemfile
+gem 'combustion', '~> 0.2.0`, :group => :development</code></pre>
+
+In your @spec_helper.rb@, get Combustion to set itself up - which has to happen before you introduce @rspec/rails@ and - if being used - @capybara/rspec@. Here's an example within context:
+
+<pre><code>require 'rubygems'
+require 'bundler'
+
+Bundler.require :default, :development
+
+Combustion.initialize!
+
+require 'rspec/rails'
+require 'capybara/rspec'
+
+RSpec.configure do |config|
+  config.use_transactional_fixtures = true
+end</code></pre>
+
+What Combustion is doing is setting up a Rails application at @spec/internal@ - but you only need to add the files within that directory that you're going to use. Read on for some detail about what that involves.
+
+h3. Configuring which Rails modules should be loaded.
+
+By default, Combustion assumes you want the full Rails stack. You can customise this though - just pass in what you'd like loaded to the @Combustion.initialize!@ call:
+
+<pre><code>Combustion.initialize! :active_record, :action_controller,
+  :action_view, :sprockets</code></pre>
+
+ActiveSupport is always loaded, as it's an integral part of Rails.
+
+h3. Using Models and ActiveRecord
+
+If you're using ActiveRecord, then there's two critical files within your internal Rails app at @spec/internal@ that you'll need to create:
+
+* config/database.yml
+* db/schema.rb
+
+Both follow the same structure as in any normal Rails application - and the schema file lets you avoid migrations, as it gets run whenever the test suite starts. Here's a quick sample (note that tables are overwritten if they already exist - this is necessary):
+
+<pre><code>ActiveRecord::Schema.define do
+  create_table(:pages, :force => true) do |t|
+    t.string :name
+    t.text   :content
+    t.timestamps
+  end
+end</code></pre>
+
+Any models that aren't provided by your engine should be located at @spec/internal/app/models@.
+
+h3. Using ActionController and ActionView
+
+You'll only need to add controllers and views to your internal Rails app for whatever you're testing that your engine doesn't provide - this may be nothing at all, so perhaps you don't even need @spec/internal/app/views@ or @spec/internal/app/controllers@ directories.
+
+However, if you're doing any testing of your engine's controllers or views, then you're going to need routes set up for them - so create a standard routes file at @spec/internal/config/routes.rb@:
+
+<pre><code>Rails.application.routes.draw do
+  resources :pages
+end</code></pre>
+
+Just like in a standard Rails app, if you have a mounted engine, then its routes are accessible through whatever it has been loaded as.
+
+h3. Environment and Logging
+
+Your tests will execute within the test environment for the internal Rails app - and so logs are available at @spec/internal/log/test.log@. You should probably create that log directory so Rails doesn't complain.
+
+h3. Rack it up
+
+Once you've got this set up, you can fire up your test environment quite easily with Rack - here's an example @config.ru@ file that could live in the root of your engine folder:
+
+<pre><code>require 'rubygems'
+require 'bundler'
+
+Bundler.require :default, :development
+
+Combustion.initialize!
+run Combustion::Application</code></pre>
+
+h3. Get your test on!
+
+Now you're good to go - you can write specs within your engine's spec directory just like you were testing a full Rails application - models in @spec/models@, controllers in @spec/controllers@. If you bring Capybara into the mix, then the standard helpers helpers from that will be loaded as well.
+
+<pre><code>require 'spec_helper'
+
+describe Page do
+  describe '#valid' do
+    it 'requires a name' do
+      # This is just an example. Go write your own tests!
+    end
+  end
+end</code></pre>
+
+h2. Compatibility
+
+Developed for Rails 3.1 and Ruby 1.9. It should work on any other Ruby, and possibly Rails 3.0, but will not work neatly with earlier versions of Rails.
+
+h2. Limitations and Known Issues
+
+Combustion is currently written with the expectation it'll be used with RSpec. I'd love to make this more flexible - if you want to give it a shot before I get around to it, patches are very much welcome.
+
+I'm also keen to have a generator that adds the standard set of files and folders (@config/database.yml@, @config/routes.rb@, @db/schema.rb@, @log@) into @spec/internal@, just to make it even easier to get going. Again, patches are welcome for this, but I'll likely get to it pretty soon.
+
+I've not tried using this with Cucumber, but it should work in theory without too much hassle. Let me know if I'm wrong!
+
+h2. Contributing
+
+Contributions are very much welcome - but keep in mind the following:
+
+* Keep patches in a separate branch
+* Don't mess with the version or history file. I'll take care of that when the patch is merged in.
+* Write tests - look at the existing tests (particularly in @spec/acceptance@)
+
+There are no tests - partly because Combustion was extracted out from the tests of HyperTiny's Dobro, and partly because there's not much code. Still, if you can find a clean way of testing this, that'd be fantastic.
+
 h2. Credits
 
-Combustion is developed and maintained by Pat Allan, and is released under the open MIT Licence.
+Copyright (c) 2011, Combustion is developed and maintained by Pat Allan, and is released under the open MIT Licence. Many thanks to HyperTiny for encouraging its development.