Set the record straight on the purpose and utility of db/schema.rb

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8124 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

Author: David Heinemeier Hansson

activerecord/lib/active_record/schema_dumper.rb

@@ -37,9 +37,16 @@ def header(stream)
         define_params = @info ? ":version => #{@info['version']}" : ""
 
         stream.puts <<HEADER
-# This file is autogenerated. Instead of editing this file, please use the
-# migrations feature of ActiveRecord to incrementally modify your database, and
+# This file is auto-generated from the current state of the database. Instead of editing this file, 
+# please use the migrations feature of ActiveRecord to incrementally modify your database, and
 # then regenerate this schema definition.
+#
+# Note that this schema.rb definition is the authoritative source for your database schema. If you need
+# to create the application database on another system, you should be using db:schema:load, not running
+# all the migrations from scratch. The latter is a flawed and unsustainable approach (the more migrations
+# you'll amass, the slower it'll run and the greater likelihood for issues).
+#
+# It's strongly recommended to check this file into your version control system.
 
 ActiveRecord::Schema.define(#{define_params}) do