NEWS bullet

NEWS.md

@@ -1,5 +1,39 @@
 # dplyr (development version)
 
+* Mutating joins now warn about multiple matches much less often. At a high
+  level, a warning was previously being thrown when a one-to-many or
+  many-to-many relationship was detected between the keys of `x` and `y`, but is
+  now only thrown for a many-to-many relationship, which is much rarer and much
+  more dangerous than one-to-many because it can result in a Cartesian explosion
+  in the number of rows returned from the join (#6731, #6717).
+
+  We've accomplished this in two steps:
+
+  * `multiple` now defaults to `"all"`, and the options of `"error"` and
+    `"warning"` are now deprecated in favor of using `relationship` (see below).
+    We are using an accelerated deprecation process for these two options
+    because they've only been available for a few weeks, and `relationship` is
+    a clearly superior alternative.
+
+  * The mutating joins gain a new `relationship` argument, allowing you to
+    enforce one of the following relationship constraints between the keys of
+    `x` and `y`: `"none"`, `"one_to_one"`, `"one_to_many"`, `"many_to_one"`,
+    `"many_to_many"`, or `"warn_many_to_many"`.
+
+    For example, `"many_to_one"` enforces that each row in `x` can match at
+    most 1 row in `y`. If a row in `x` matches >1 rows in `y`, an error is
+    thrown. This option serves as the replacement for `multiple = "error"`.
+
+    For equality joins, `relationship` defaults to `"warn_many_to_many"` to
+    warn if an unexpected many-to-many relationship is detected, and otherwise
+    defaults to `"none"` for inequality, rolling, and overlap joins.
+
+  This change unfortunately does mean that if you have set `multiple = "all"` to
+  avoid a warning and you happened to be doing a many-to-many style join, then
+  you will need to replace `multiple = "all"` with
+  `relationship = "many_to_many"` to silence the new warning, but we believe
+  this should be rare since many-to-many relationships are fairly uncommon.
+
 * `group_data()` on ungrouped data frames is faster (#6736).
 
 * `n()` is now a little faster when there are many groups (#6727).