@@ -345,30 +345,97 @@ pub struct FutureIncompatibleInfo {
345
345
}
346
346
347
347
/// The reason for future incompatibility
348
+ ///
349
+ /// Future-incompatible lints come in roughly two categories:
350
+ ///
351
+ /// 1. There was a mistake in the compiler (such as a soundness issue), and
352
+ /// we're trying to fix it, but it may be a breaking change.
353
+ /// 2. A change across an Edition boundary, typically used for the
354
+ /// introduction of new language features that can't otherwise be
355
+ /// introduced in a backwards-compatible way.
356
+ ///
357
+ /// See <https://rustc-dev-guide.rust-lang.org/bug-fix-procedure.html> and
358
+ /// <https://rustc-dev-guide.rust-lang.org/diagnostics.html#future-incompatible-lints>
359
+ /// for more information.
348
360
#[ derive( Copy , Clone , Debug ) ]
349
361
pub enum FutureIncompatibilityReason {
350
362
/// This will be an error in a future release for all editions
351
363
///
352
364
/// This will *not* show up in cargo's future breakage report.
353
365
/// The warning will hence only be seen in local crates, not in dependencies.
366
+ ///
367
+ /// Choose this variant when you are first introducing a "future
368
+ /// incompatible" warning that is intended to eventually be fixed in the
369
+ /// future. This allows crate developers an opportunity to fix the warning
370
+ /// before blasting all dependents with a warning they can't fix
371
+ /// (dependents have to wait for a new release of the affected crate to be
372
+ /// published).
373
+ ///
374
+ /// After a lint has been in this state for a while, consider graduating
375
+ /// it to [`FutureIncompatibilityReason::FutureReleaseErrorReportInDeps`].
354
376
FutureReleaseErrorDontReportInDeps ,
355
377
/// This will be an error in a future release, and
356
378
/// Cargo should create a report even for dependencies
357
379
///
358
380
/// This is the *only* reason that will make future incompatibility warnings show up in cargo's
359
381
/// reports. All other future incompatibility warnings are not visible when they occur in a
360
382
/// dependency.
383
+ ///
384
+ /// Choose this variant after the lint has been sitting in the
385
+ /// [`FutureIncompatibilityReason::FutureReleaseErrorDontReportInDeps`]
386
+ /// state for a while, and you feel like it is ready to graduate to
387
+ /// warning everyone. It is a good signal that it is ready if you can
388
+ /// determine that all or most affected crates on crates.io have been
389
+ /// updated.
390
+ ///
391
+ /// After some period of time, lints with this variant can be turned into
392
+ /// hard errors (and the lint removed). Preferably when there is some
393
+ /// confidence that the number of impacted projects is very small (few
394
+ /// should have a broken dependency in their dependency tree).
361
395
FutureReleaseErrorReportInDeps ,
362
396
/// Code that changes meaning in some way in a
363
397
/// future release.
398
+ ///
399
+ /// Choose this variant when the semantics of existing code is changing,
400
+ /// (as opposed to
401
+ /// [`FutureIncompatibilityReason::FutureReleaseErrorDontReportInDeps`],
402
+ /// which is for when code is going to be rejected in the future).
364
403
FutureReleaseSemanticsChange ,
365
404
/// Previously accepted code that will become an
366
405
/// error in the provided edition
406
+ ///
407
+ /// Choose this variant for code that you want to start rejecting across
408
+ /// an edition boundary. This will automatically include the lint in the
409
+ /// `rust-20xx-compatibility` lint group, which is used by `cargo fix
410
+ /// --edition` to do migrations. The lint *should* be auto-fixable with
411
+ /// [`Applicability::MachineApplicable`].
412
+ ///
413
+ /// The lint can either be `Allow` or `Warn` by default. If it is `Allow`,
414
+ /// users usually won't see this warning unless they are doing an edition
415
+ /// migration manually or there is a problem during the migration (cargo's
416
+ /// automatic migrations will force the level to `Warn`). If it is `Warn`
417
+ /// by default, users on all editions will see this warning (only do this
418
+ /// if you think it is important for everyone to be aware of the change,
419
+ /// and to encourage people to update their code on all editions).
420
+ ///
421
+ /// See also [`FutureIncompatibilityReason::EditionSemanticsChange`] if
422
+ /// you have code that is changing semantics across the edition (as
423
+ /// opposed to being rejected).
367
424
EditionError ( Edition ) ,
368
425
/// Code that changes meaning in some way in
369
426
/// the provided edition
427
+ ///
428
+ /// This is the same as [`FutureIncompatibilityReason::EditionError`],
429
+ /// except for situations where the semantics change across an edition. It
430
+ /// slightly changes the text of the diagnostic, but is otherwise the
431
+ /// same.
370
432
EditionSemanticsChange ( Edition ) ,
371
433
/// A custom reason.
434
+ ///
435
+ /// Choose this variant if the built-in text of the diagnostic of the
436
+ /// other variants doesn't match your situation. This is behaviorally
437
+ /// equivalent to
438
+ /// [`FutureIncompatibilityReason::FutureReleaseErrorDontReportInDeps`].
372
439
Custom ( & ' static str ) ,
373
440
}
374
441
0 commit comments