@@ -184,14 +184,29 @@ considerate to at least notify the authors of affected crates the
184
184
breaking change. If we can submit PRs to fix the problem, so much the
185
185
better.
186
186
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.
195
210
2 . Try to give a very precise error message that suggests how to fix
196
211
the problem and directs users to the tracking issue.
197
212
3 . It may also make sense to layer the fix:
@@ -201,13 +216,7 @@ strategy is to mitigate:
201
216
versions are available * before* the fix lands, so that downstream
202
217
users can use them.
203
218
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
+
211
220
### Stabilization
212
221
213
222
After a change is made, we will ** stabilize** the change using the same
@@ -221,6 +230,9 @@ process that we use for unstable features:
221
230
- Convert to error: the change should be made into a hard error.
222
231
- Revert: we should remove the warning and continue to allow the older code to compile.
223
232
- 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.
224
236
225
237
### Batching breaking changes to libsyntax
226
238
0 commit comments