revises the contributing guide to document and encourage using the Rails development box

1 files changed, 33 insertions, 27 deletions

diff --git a/guides/source/contributing_to_ruby_on_rails.textile b/guides/source/contributing_to_ruby_on_rails.textile
index 02b4c65d37..65db40e77d 100644
--- a/guides/source/contributing_to_ruby_on_rails.textile
+++ b/guides/source/contributing_to_ruby_on_rails.textile
@@ -36,11 +36,17 @@ Please don't put "feature request" items into GitHub Issues. If there's a new fe
 
 If you'd like feedback on an idea for a feature before doing the work for make a patch, please send an email to the "rails-core mailing list":https://groups.google.com/forum/?fromgroups#!forum/rubyonrails-core. You might get no response, which means that everyone is indifferent. You might find someone who's also interested in building that feature. You might get a "This won't be accepted." But it's the proper place to discuss new ideas. GitHub Issues are not a particularly good venue for the sometimes long and involved discussions new features require.
 
-h3. Running the Test Suite
+h3. Setting Up a Development Environment
 
 To move on from submitting bugs to helping resolve existing issues or contributing your own code to Ruby on Rails, you _must_ be able to run its test suite. In this section of the guide you'll learn how to set up the tests on your own computer.
 
-h4. Install Git
+h4. The Easy Way
+
+The easiest way to get a development environment ready to hack is to use the "Rails development box":https://github.com/rails/rails-dev-box.
+
+h4. The Hard Way
+
+h5. Install Git
 
 Ruby on Rails uses git for source code control. The "git homepage":http://git-scm.com/ has installation instructions. There are a variety of resources on the net that will help you get familiar with git:
 
@@ -49,7 +55,7 @@ Ruby on Rails uses git for source code control. The "git homepage":http://git-sc
 * "GitHub":http://help.github.com offers links to a variety of git resources.
 * "Pro Git":http://progit.org/book/ is an entire book about git with a Creative Commons license.
 
-h4. Clone the Ruby on Rails Repository
+h5. Clone the Ruby on Rails Repository
 
 Navigate to the folder where you want the Ruby on Rails source code (it will create its own +rails+ subdirectory) and run:
 
@@ -58,7 +64,7 @@ $ git clone git://github.com/rails/rails.git
 $ cd rails
 </shell>
 
-h4. Set up and Run the Tests
+h5. Set up and Run the Tests
 
 The test suite must pass with any submitted code. No matter whether you are writing a new patch, or evaluating someone else's, you need to be able to run the tests.
 
@@ -128,36 +134,17 @@ $ cd actionpack
 $ bundle exec ruby -Itest test/template/form_helper_test.rb
 </shell>
 
-h4. Warnings
-
-The test suite runs with warnings enabled. Ideally, Ruby on Rails should issue no warnings, but there may be a few, as well as some from third-party libraries. Please ignore (or fix!) them, if any, and submit patches that do not issue new warnings.
-
-As of this writing (December, 2010) they are specially noisy with Ruby 1.9. If you are sure about what you are doing and would like to have a more clear output, there's a way to override the flag:
-
-<shell>
-$ RUBYOPT=-W0 bundle exec rake test
-</shell>
-
-h4. Testing Active Record
+h5. Active Record Setup
 
 The test suite of Active Record attempts to run four times: once for SQLite3, once for each of the two MySQL gems (+mysql+ and +mysql2+), and once for PostgreSQL. We are going to see now how to set up the environment for them.
 
 WARNING: If you're working with Active Record code, you _must_ ensure that the tests pass for at least MySQL, PostgreSQL, and SQLite3. Subtle differences between the various adapters have been behind the rejection of many patches that looked OK when tested only against MySQL.
 
-h5. Database Configuration
+h6. Database Configuration
 
 The Active Record test suite requires a custom config file: +activerecord/test/config.yml+. An example is provided in +activerecord/test/config.example.yml+ which can be copied and used as needed for your environment.
 
-h5. SQLite3
-
-The gem +sqlite3-ruby+ does not belong to the "db" group. Indeed, if you followed the instructions above you're ready. This is how you run the Active Record test suite only for SQLite3:
-
-<shell>
-$ cd activerecord
-$ bundle exec rake test_sqlite3
-</shell>
-
-h5. MySQL and PostgreSQL
+h6. MySQL and PostgreSQL
 
 To be able to run the suite for MySQL and PostgreSQL we need their gems. Install first the servers, their client libraries, and their development files. In Ubuntu just run
 
@@ -217,6 +204,15 @@ NOTE: You'll see the following warning (or localized warning) during activating
 
 If you’re using another database, check the file +activerecord/test/config.yml+ or +activerecord/test/config.example.yml+ for default connection information. You can edit +activerecord/test/config.yml+ to provide different credentials on your machine if you must, but obviously you should not push any such changes back to Rails.
 
+h3. Testing Active Record
+
+This is how you run the Active Record test suite only for SQLite3:
+
+<shell>
+$ cd activerecord
+$ bundle exec rake test_sqlite3
+</shell>
+
 You can now run the tests as you did for +sqlite3+. The tasks are respectively
 
 <shell>
@@ -225,7 +221,7 @@ test_mysql2
 test_postgresql
 </shell>
 
-As we mentioned before
+Finally,
 
 <shell>
 $ bundle exec rake test
@@ -241,6 +237,16 @@ $ ARCONN=sqlite3 ruby -Itest test/cases/associations/has_many_associations_test.
 
 You can invoke +test_jdbcmysql+, +test_jdbcsqlite3+ or +test_jdbcpostgresql+ also. See the file +activerecord/RUNNING_UNIT_TESTS+ for information on running more targeted database tests, or the file +ci/travis.rb+ for the test suite run by the continuous integration server.
 
+h4. Warnings
+
+The test suite runs with warnings enabled. Ideally, Ruby on Rails should issue no warnings, but there may be a few, as well as some from third-party libraries. Please ignore (or fix!) them, if any, and submit patches that do not issue new warnings.
+
+As of this writing (December, 2010) they are specially noisy with Ruby 1.9. If you are sure about what you are doing and would like to have a more clear output, there's a way to override the flag:
+
+<shell>
+$ RUBYOPT=-W0 bundle exec rake test
+</shell>
+
 h4. Older Versions of Ruby on Rails
 
 If you want to add a fix to older versions of Ruby on Rails, you'll need to set up and switch to your own local tracking branch. Here is an example to switch to the 3-0-stable branch: