Skip to content

Commit ad996de

Browse files
committed
adjust wording to allow for "small changes"
1 parent ec1a4b7 commit ad996de

File tree

1 file changed

+27
-15
lines changed

1 file changed

+27
-15
lines changed

text/0000-rustc-bug-fix-procedure.md

+27-15
Original file line numberDiff line numberDiff line change
@@ -184,14 +184,29 @@ considerate to at least notify the authors of affected crates the
184184
breaking change. If we can submit PRs to fix the problem, so much the
185185
better.
186186

187-
#### What if issuing a warning is too hard?
188-
189-
It does happen from time to time that it is nigh impossible to isolate
190-
the breaking change so that you can issue warnings. In such cases, the best
191-
strategy is to mitigate:
192-
193-
1. Issue warnings for subparts of the problem, and reserve the new errors for
194-
the smallest set of cases you can.
187+
#### Is it ever acceptable to go directly to issuing errors?
188+
189+
Changes that are believed to have negligible impact can go directly to
190+
issuing an error. One rule of thumb would be to check against
191+
`crates.io`: if fewer than 10 **total** affected projects are found
192+
(**not** root errors), we can move straight to an error. In such
193+
cases, we should still make the "breaking change" page as before, and
194+
we should ensure that the error directs users to this page. In other
195+
words, everything should be the same except that users are getting an
196+
error, and not a warning. Moreover, we should submit PRs to the
197+
affected projects (ideally before the PR implementing the change lands
198+
in rustc).
199+
200+
If the impact is not believed to be negligible (e.g., more than 10
201+
crates are affected), then warnings are required (unless the compiler
202+
team agrees to grant a special exemption in some particular case). If
203+
implementing warnings is not feasible, then we should make an
204+
aggressive strategy of migrating crates before we land the change so
205+
as to lower the number of affected crates. Here are some techniques
206+
for approaching this scenario:
207+
208+
1. Issue warnings for subparts of the problem, and reserve the new
209+
errors for the smallest set of cases you can.
195210
2. Try to give a very precise error message that suggests how to fix
196211
the problem and directs users to the tracking issue.
197212
3. It may also make sense to layer the fix:
@@ -201,13 +216,7 @@ strategy is to mitigate:
201216
versions are available *before* the fix lands, so that downstream
202217
users can use them.
203218

204-
If you will be issuing a new hard warning, then it is mandatory to at
205-
least notify authors of affected crates which we know
206-
about. Submitting PRs to fix the problem is strongly recommended. If
207-
the impact is too large to make that practical, then we should try
208-
harder to issue warnings or find a way to avoid making the change at
209-
all.
210-
219+
211220
### Stabilization
212221

213222
After a change is made, we will **stabilize** the change using the same
@@ -221,6 +230,9 @@ process that we use for unstable features:
221230
- Convert to error: the change should be made into a hard error.
222231
- Revert: we should remove the warning and continue to allow the older code to compile.
223232
- Defer: can't decide yet, wait longer, or try other strategies.
233+
234+
Ideally, breaking changes should have landed on the **stable branch**
235+
of the compiler before they are finalized.
224236

225237
### Batching breaking changes to libsyntax
226238

0 commit comments

Comments
 (0)