From dc9615928a34f793233f581ad80cdc9806c69516 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Thu, 21 Nov 2024 20:57:55 -0800
Subject: [PATCH 1/2] SemVer: Add section on RPIT capturing

---
 src/doc/src/reference/semver.md | 42 +++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/src/doc/src/reference/semver.md b/src/doc/src/reference/semver.md
index c06720f6c69..b48fdc3469d 100644
--- a/src/doc/src/reference/semver.md
+++ b/src/doc/src/reference/semver.md
@@ -81,6 +81,7 @@ considered incompatible.
         * [Minor: generalizing a type to use generics (with identical types)](#generic-generalize-identical)
         * [Major: generalizing a type to use generics (with possibly different types)](#generic-generalize-different)
         * [Minor: changing a generic type to a more generic type](#generic-more-generic)
+        * [Major: capturing more generic parameters in RPIT](#generic-rpit-capture)
     * Functions
         * [Major: adding/removing function parameters](#fn-change-arity)
         * [Possibly-breaking: introducing a new function type parameter](#fn-generic-new)
@@ -1616,6 +1617,47 @@ fn main() {
 }
 ```
 
+### Major: capturing more generic parameters in RPIT {#generic-rpit-capture}
+
+It is a breaking change to capture additional generic parameters in an [RPIT] (return-position impl trait).
+
+```rust,ignore
+// MAJOR CHANGE
+
+///////////////////////////////////////////////////////////
+// Before
+pub fn f<'a, 'b>(x: &'a str, y: &'b str) -> impl Iterator<Item = char> + use<'a> {
+    x.chars()
+}
+
+///////////////////////////////////////////////////////////
+// After
+pub fn f<'a, 'b>(x: &'a str, y: &'b str) -> impl Iterator<Item = char> + use<'a, 'b> {
+    x.chars().chain(y.chars())
+}
+
+///////////////////////////////////////////////////////////
+// Example usage that will break.
+fn main() {
+    let a = String::new();
+    let b = String::new();
+    let iter = updated_crate::f(&a, &b);
+    drop(b); // Error: cannot move out of `b` because it is borrowed
+}
+```
+
+Adding generic parameters to an RPIT places additional constraints on how the resulting type may be used.
+
+Note that there are implicit captures when the `use<>` syntax is not specified. In Rust 2021 and earlier editions, the lifetime parameters are only captured if they appear syntactically within a bound in the RPIT type signature. Starting in Rust 2024, all lifetime parameters are unconditionally captured. This means that starting in Rust 2024, the default is maximally compatible, requiring you to be explicit when you want to capture less, which is a SemVer commitment.
+
+See the [edition guide][rpit-capture-guide] and the [reference][rpit-reference] for more information on RPIT capturing.
+
+It is a minor change to capture fewer generic parameters in an RPIT.
+
+[RPIT]: ../../reference/types/impl-trait.md#abstract-return-types
+[rpit-capture-guide]: ../../edition-guide/rust-2024/rpit-lifetime-capture.html
+[rpit-reference]: ../../reference/types/impl-trait.md#capturing
+
 ### Major: adding/removing function parameters {#fn-change-arity}
 
 Changing the arity of a function is a breaking change.

From f06d53827d0a05018aa640c3ab8759071b18a70b Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Sun, 8 Dec 2024 06:54:36 -0800
Subject: [PATCH 2/2] Add note about type and const generics

---
 src/doc/src/reference/semver.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/doc/src/reference/semver.md b/src/doc/src/reference/semver.md
index b48fdc3469d..232f7f3ac50 100644
--- a/src/doc/src/reference/semver.md
+++ b/src/doc/src/reference/semver.md
@@ -1654,6 +1654,8 @@ See the [edition guide][rpit-capture-guide] and the [reference][rpit-reference]
 
 It is a minor change to capture fewer generic parameters in an RPIT.
 
+> Note: All in-scope type and const generic parameters must be either implicitly captured (no `+ use<…>` specified) or explicitly captured (must be listed in `+ use<…>`), and thus currently it is not allowed to change what is captured of those kinds of generics.
+
 [RPIT]: ../../reference/types/impl-trait.md#abstract-return-types
 [rpit-capture-guide]: ../../edition-guide/rust-2024/rpit-lifetime-capture.html
 [rpit-reference]: ../../reference/types/impl-trait.md#capturing