[Fix #237] Improve documentation for Rails/NotNullColumn

Clarify that the cop is only for NOT NULL without a default, and only
for existing tables. Also point users in the direction of how to
add a NOT NULL column to an existing table.

config/default.yml

@@ -693,7 +693,7 @@ Rails/NegateInclude:
   VersionChanged: '2.9'
 
 Rails/NotNullColumn:
-  Description: 'Do not add a NOT NULL column without a default value.'
+  Description: 'Do not add a NOT NULL column without a default value to existing tables.'
   Enabled: true
   VersionAdded: '0.43'
   VersionChanged: '2.20'

lib/rubocop/cop/rails/not_null_column.rb

@@ -3,13 +3,25 @@
 module RuboCop
   module Cop
     module Rails
-      # Checks for add_column call with NOT NULL constraint in migration file.
+      # Checks for add_column calls with a NOT NULL constraint without a default
+      # value.
       #
-      # `TEXT` can have default values in PostgreSQL, but not in MySQL.
-      # It will automatically detect an adapter from `development` environment
-      # in `config/database.yml` or the environment variable `DATABASE_URL`
-      # when the `Database` option is not set. If the database is MySQL,
-      # this cop ignores offenses for the `TEXT`.
+      # This cop only applies when adding a column to an existing table, since
+      # existing records will not have a value for the new column. New tables
+      # can freely use NOT NULL columns without defaults, since there are no
+      # records that could violate the constraint.
+      #
+      # If you need to add a NOT NULL column to an existing table, you must add
+      # it as nullable first, back-fill the data, and then use
+      # `change_column_null`. Alternatively, you could add the column with a
+      # default first to have the database automatically backfill existing rows,
+      # and then use `change_column_default` to remove the default.
+      #
+      # `TEXT` cannot have a default value in MySQL.
+      # The cop will automatically detect an adapter from `development`
+      # environment in `config/database.yml` or the environment variable
+      # `DATABASE_URL` when the `Database` option is not set. If the database
+      # is MySQL, this cop ignores offenses for `TEXT` columns.
       #
       # @example
       #   # bad
@@ -20,7 +32,7 @@ module Rails
       #   add_column :users, :name, :string, null: true
       #   add_column :users, :name, :string, null: false, default: ''
       #   add_reference :products, :category
-      #   add_reference :products, :category, null: false, default: 1
+      #   change_column_null :products, :category_id, false
       class NotNullColumn < Base
         include DatabaseTypeResolvable