This patch
  - reduces the duplication among the `reference`-family methods.
  - better explains all the optians available for `add_reference`.
  - redirects to user from `references` to `add_reference`.

Originated by #20184.

Some databases like MySQL allow defining collation charset for specific
columns.

The `index` option used with `timestamps` should be passed to both
`column` definitions for `created_at` and `updated_at` rather than just
the first.

This was happening because `Hash#delete` is used to extract the `index`
option passed to `timestamps`, thereby mutating the `options` hash
in-place. Now take a copy of the `options` before deleting so that the
original is not modified.

test case for use singular table name if pluralize_table_names is setted as false while creating foreign key

refactor references foreign key addition tests

use singular table name while removing foreign key

merge foreign key singular table name methods

remove unnecessary drop table from test

- Add example to column_exists?
- Add example to index_exists?
- Add document for foreign_key
- Add document for foreign_key_exists?

This is no longer needed.

`visit_ChangeColumnDefinition` is the same "CHANGE column_name " + `visit_ColumnDefinition(o)`.

Example:

    create_table :foos, id: :bigint do |t|
    end

Most of the documentation very closely mirrors the matching
docs from `SchemaStatements`. I reduced duplicated copy and
added links to the underlying methods for the user to follow.

The code for `TableDefinition#references` and
`SchemaStatements#add_reference` were almost identical both
structurally, and in terms of domain knowledge. This removes that
duplication into a common class, using the `Table` API as the expected
interface of its collaborator.

This has the same comments as 9af90ffa00ba35bdee888e3e1ab775ba0bdbe72c,
however it affects the `add_reference` method, and `t.references` in the
context of a `change_table` block.

There is a lot of duplication of code between creating and updating
tables. We should re-evaluate the structure of this code from a high
level so changes like this don't need to be made in two places. (Note to
self)

Rather than having to do:

    create_table :posts do |t|
      t.references :user
    end

    add_foreign_key :posts, :users

You can instead do:

    create_table :posts do |t|
      t.references :user, foreign_key: true
    end

Similar to the `index` option, you can also pass a hash. This will be
passed as the options to `add_foreign_key`. e.g.:

    create_table :posts do |t|
      t.references :user, foreign_key: { primary_key: :other_id }
    end

is equivalent to

    create_table :posts do |t|
      t.references :user
    end

    add_foreign_key :posts, :users, primary_key: :other_id

While we aren't taking PRs with these kinds of changes just yet, they
are fine if we're actively working on the method and it makes things
easier.

When running the following migration:

    change_table(:table_name) { |t| t/timestamps }

The following error was produced:

    wrong number of arguments (2 for 1) .... /connection_adapters/abstract/schema_statements.rb:851:in `remove_timestamps'

This is due to `arguments` containing an empty hash as its second
argument.

This makes the following changes:
  * warn if `:null` is not passed to `add_timestamps`
  * `timestamps` method docs link to `add_timestamps` docs
  * explain where additional options go
  * adjust examples to include `null: false` (to prevent deprecation warnings)

This patch uniformizes warning messages. I used the most common style
already present in the code base:

* Capitalize the first word.

* End the message with a full stop.

* "Rails 5" instead of "Rails 5.0".

* Backticks for method names and inline code.

Also, converted a few long strings into the new heredoc convention.

The current style for warning messages without newlines uses
concatenation of string literals with manual trailing spaces
where needed.

Heredocs have better readability, and with `squish` we can still
produce a single line.

This is a similar use case to the one that motivated defining
`strip_heredoc`, heredocs are super clean.

`add_reference` can very helpfully add a multi-column index when you use
it to add a polymorphic reference. However, the first column in the
index is the `id` column, which is less than ideal.

The [PostgreSQL docs][1] say:
> A multicolumn B-tree index can be used with query conditions that
> involve any subset of the index's columns, but the index is most
> efficient when there are constraints on the leading (leftmost)
> columns.

The [MySQL docs][2] say:
> MySQL can use multiple-column indexes for queries that test all the
> columns in the index, or queries that test just the first column, the
> first two columns, the first three columns, and so on. If you specify
> the columns in the right order in the index definition, a single
> composite index can speed up several kinds of queries on the same
> table.

In a polymorphic relationship, the type column is much more likely to be
useful as the first column in an index than the id column. That is, I'm
more likely to query on type without an id than I am to query on id
without a type.

[1]: http://www.postgresql.org/docs/9.3/static/indexes-multicolumn.html
[2]: http://dev.mysql.com/doc/refman/5.0/en/multiple-column-indexes.html

In the DSL you can now do:

create_table(:foos) do |t|
  t.bigint :hi
end

TableDefinition#column is not called from `add_column`.
Use TableDefinition#new_column_definition for column option handling.

Method .strip_heredoc is defined in
active_support/core_ext/string/strip.rb so we need to require it.

[fixes #16677]

Using heredoc would enforce line wrapping to whatever column width we decided to
use in the code, making it difficult for the users to read on some consoles.

This does make the source code read slightly worse and a bit more error-prone,
but this seems like a fair price to pay since the primary purpose for these
messages are for the users to read and the code will not stick around for too
long.

`strip_heredoc` method is defined on active_support/core_ext/string

As per discussion, this changes the model generators to specify
`null: false` for timestamp columns. A warning is now emitted if
`timestamps` is called without a `null` option specified, so we can
safely change the behavior when no option is specified in Rails 5.

[Andrey Novikov & Łukasz Sarnacki]