I'm pretty confused about the addition of this method. The documentation
says that it was intended to allow the removal of values from the
default scope (in contrast to #except). However it behaves exactly the
same as except: https://gist.github.com/jonleighton/7537008 (other than
having a slightly enhanced syntax).

The removal of the default scope is allowed by
94924dc3, which was not a change we
could make until 4.1 due to the need to deprecate things. However after
that change #unscope still gives us nothing that #except doesn't already
give us.

However there *is* a desire to be able to unscope stuff in a way that
persists across merges, which would allow associations to be defined
which unscope stuff from the default scope of the associated model. E.g.

  has_many :comments, -> { unscope where: :trashed }

So that's what this change implements. I've also corrected the
documentation. I removed the guide references to #except as I think
unscope really supercedes #except now.

While we're here, there's also a potential desire to be able to write
this:

  has_many :comments, -> { unscoped }

However, it doesn't make sense and would not be straightforward to
implement. While with #unscope we're specifying exactly what we want to
be removed from the relation, with "unscoped" we're just saying that we
want it to not have some things which were added earlier on by the
default scope. However in the case of an association, we surely don't
want *all* conditions to be removed, otherwise the above would just
become "SELECT * FROM comments" with no foreign key constraint.

To make the above work, we'd have to somehow tag the relation values
which get added when evaluating the default scope in order to
differentiate them from other relation values. Which is way too much
complexity and therefore not worth it when most use cases can be
satisfied with unscope.

Closes #10643, #11061.

This fixes a bug when merging relations of different classes.

```
Given:
  Post.joins(:author).merge(Author.order(name: :desc)).to_sql

Before:
 SELECT "posts".* FROM "posts"
   INNER JOIN "authors" ON "authors"."id" = "posts"."author_id"
   ORDER BY "posts"."name" DESC

After:
 SELECT "posts".* FROM "posts"
   INNER JOIN "authors" ON "authors"."id" = "posts"."author_id"
   ORDER BY "authors"."name" DESC
```

According to our guideline, we leave 1 space between `#` and `=>`, so we
want `# =>` instead of `#=>`.

Thanks to @fxn for the suggestion.

[ci skip]

Allows you to call #unscope on a relation with negative equality operators,
i.e. Arel::Nodes::NotIn and Arel::Nodes::NotEqual that have been generated
through the use of where.not.

Generated sub-query for Relation as array condition for `where` method
did not take in account its bind values, in result generates invalid SQL query.

Fixed by adding sub-query relation's binding values to base relation

Closes: #12586

Merge JoinDependency objects as outer joins

In order to remove duplication with joining arel where constraints with
`AND`, all constraints on `build_arel` are collapsed into one head node: `Arel::Nodes::And`

Closes: #11963

- Use symbols rather than strings where possible to avoid extra object construction
- Use destructive methods where possible to avoid extra object construction
- Use array union rather than concat followed by uniq
- Use shorthand block syntax where possible
- Use consistent multiline block styles, method names, method parenteses style, and spacing

order on the old ones

The previous behavior added a major backward incompatibility since it
impossible to have a upgrade path without major changes on the
application code.

We are taking the most conservative path to be consistent with the idea
of having a smoother upgrade on Rails 4.

We are reverting the behavior for what was in Rails 3.x and,
if needed, we will implement a new API to prepend the order clauses in
Rails 4.1.

It's not immediately clear whether you can pass in multiple relations or
not. After going through the code a bit, I saw that the arguments are
just appended to an array. Also, added nested relations example.

[ci skip]

Stop special-casing Arel::Nodes as exempt from reference scanning in
order. Instead, only scan order values that are strings for a table
reference.

The previous implementation was necessary in order to support stuff
like:

    class Post < ActiveRecord::Base
      default_scope where(published: true)
      scope :ordered, order("created_at")
    end

If we didn't evaluate the default scope at the last possible moment
before sending the SQL to the database, it would become impossible to
do:

    Post.unscoped.ordered

This is because the default scope would already be bound up in the
"ordered" scope, and therefore wouldn't be removed by the
"Post.unscoped" part.

In 4.0, we have deprecated all "eager" forms of scopes. So now you must
write:

    class Post < ActiveRecord::Base
      default_scope { where(published: true) }
      scope :ordered, -> { order("created_at") }
    end

This prevents the default scope getting bound up inside the "ordered"
scope, which means we can now have a simpler/better/more natural
implementation of default scoping.

A knock on effect is that some things that didn't work properly now do.
For example it was previously impossible to use #except to remove a part
of the default scope, since the default scope was evaluated after the
call to #except.

fixes #10669

While joining_values special treatment is given to string values.
By flattening the array it ensures that string values are detected
as strings and not arrays.

pass block directly to grep

[ci skip]

The similarity of `Relation#uniq` to `Array#uniq` is confusing. Since our
Relation API is close to SQL terms I renamed `#uniq` to `#distinct`.

There is no deprecation. `#uniq` and `#uniq!` are aliases and will continue
to work. I also updated the documentation to promote the use of `#distinct`.