Deprecate passing rewhere to merge

[HParker]

In 6.1 rewhere was added to merge in #39250 to get more consistent merge behavior.

Sometimes maintaining both conditions on merge calls was removed as default behavior in 7.0: 515aa1e

the release notes,

rails/guides/source/7_0_release_notes.md

Line 211 in 630342e

# Rails 6.1 with rewhere to migrate to Rails 7.0's behavior

and the original deprecation warning,

https://github.com/rails/rails/blob/6-1-stable/activerecord/lib/active_record/relation/where_clause.rb#L169-L173

both show rewhere: true as a way to migrate your 6.1 app to 7.0.

Now that 7.0 is released we can deprecate rewhere as an option on merge and eventually remove the non-rewhere version of merge.

[matthewd]

Suggested change

	Setting `rewhere: false` is deprecated and will be removed in Rails 7.2
	in Rails 7.2 merge will no longer maintain both conditions,
	and will be consistently replaced by the latter condition.
	`Relation#merge(rewhere: false)` is deprecated without replacement,
	and will be removed in Rails 7.2

The proposed message would've looked quite odd after squashing ("in Rails 7.2 in Rails 7.2").

The best thing a deprecation message can communicate is not why it's changing, but what the user needs to do to respond... in this case, we don't have a good answer beyond "figure it out for yourself"; that's not generally an ideal thing to dump onto the user, but in this case we're not expecting people to actually be using this option at all, so a more abrupt "this is going to stop working, soz" seems acceptable.

IMO we don't need to try to fit a "why this is better" into a handful of words here, because 1) the user doesn't care that it's better in principle: what they have is working for them, and 2) the user knows what the option does, because they recently went out of their way to adopt it.

[msakrejda]

Isn't #and a possible alternative here?

[matthewd]

Suggested change

	Setting `rewhere: true` is deprecated. `rewhere: true` is the default behavior since Rails 7.0.
	This option is no longer needed and will be removed in Rails 7.2
	Specifying `Relation#merge(rewhere: true)` is deprecated, as that has now been
	the default since Rails 7.0. Setting the rewhere option will error in Rails 7.2

A lot of deprecation messages end in some form of "will be removed in Rails x.y", for good reason, but sometimes I think there are better ways of establishing the same "you need to act before your next upgrade".

[HParker]

Thanks @matthewd! I updated both messages and tried to make them more similar while I was there.

for the rewhere: false case I went with,

Specifying `Relation#merge(rewhere: false)` is deprecated and will be removed in Rails 7.2.
Remove `rewhere: false` and assure your code expects merge to overwrite conditions.

I think we could still add more information, but I am relying on the fact that if you are using rewhere on merge you probably at least know what rewhere on merge did before. Alternatively we can add to the docs and link it here. I am happy to do that work if you think it is necessary. I don't believe there is a good section of documentation to link to today.

for rewhere: true

Specifying `Relation#merge(rewhere: true)` is deprecated, as that has now been
the default since Rails 7.0. You can remove this option and behavior will not change.
The `rewhere:` option will be removed in Rails 7.2.

I adopted your message almost exactly, except I said the option is removed instead of the option will error since I am not confident it will error unless we purposefully make it error.

I don't feel strongly, about either message, so I am happy to adjust them again!

[HParker]

On second thought I like @matthewd's wording a lot.