If it is `Allow`, users usually won't see this warning unless they are doing an edition migration
manually or there is a problem during the migration.
Most migration lints are `Allow`.

If it is `Warn` by default, users on all editions will see this warning.
Only use `Warn` if you think it is important for everyone to be aware of the change, and to
encourage people to update their code on all editions.
Beware that new warn-by-default lint that hit many projects can be very disruptive and frustrating
for users.
You may consider switching an `Allow` to `Warn` several years after the edition stabilizes.
This will only show up for the relatively small number of stragglers who have not updated to the new
edition.

[`keyword_idents`]: https://doc.rust-lang.org/nightly/rustc/lints/listing/allowed-by-default.html#keyword-idents
[`FutureIncompatibilityReason::EditionError`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint_defs/enum.FutureIncompatibilityReason.html#variant.EditionError
[`FutureIncompatibilityReason::EditionSemanticsChange`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint_defs/enum.FutureIncompatibilityReason.html#variant.EditionSemanticsChange

### Edition-specific lints

Lints can be marked so that they have a different level starting in a specific edition.
In the lint declaration, use the `@edition` marker:

```rust,ignore
declare_lint! {
    pub SOME_LINT_NAME,
    Allow,
    "my lint description",
    @edition Edition2024 => Warn;
}
```

Here, `SOME_LINT_NAME` defaults to `Allow` on all editions before 2024, and then becomes `Warn`
afterwards.

This should generally be used sparingly, as there are other options:

- Small impact stylistic changes unrelated to an edition can just make the lint `Warn` on all
  editions. If you want people to adopt a different way to write things, then go ahead and commit to
  having it show up for all projects.

  Beware that if a new warn-by-default lint hits many projects, it can be very disruptive and
  frustrating for users.

- Change the new style to be a hard error in the new edition, and use a [migration lint] to
  automatically convert projects to the new style. For example,
  [`ellipsis_inclusive_range_patterns`] is a hard error in 2021, and warns in all previous editions.

  Beware that these cannot be added after the edition stabilizes.

- Migration lints can also change over time.
  For example, the migration lint can start out as `Allow` by default.
  For people performing the migration, they will automatically get updated to the new code.
  Then, after some years, the lint can be made to `Warn` in previous editions.

  For example [`anonymous_parameters`] was a 2018 Edition migration lint (and a hard-error in 2018)
  that was `Allow` by default in previous editions.
  Then, three years later, it was changed to `Warn` for all previous editions, so that all users got
  a warning that the style was being phased out.
  If this was a warning from the start, it would have impacted many projects and be very disruptive.
  By making it part of the edition, most users eventually updated to the new edition and were
  handled by the migration.
  Switching to `Warn` only impacted a few stragglers who did not update.


### Lints and stability

Lints can be marked as being unstable, which can be helpful when developing a new edition feature,
and you want to test out a migration lint.
The feature gate can be specified in the lint's declaration like this:

```rust,ignore
declare_lint! {
    pub SOME_LINT_NAME,
    Allow,
    "my cool lint",
    @feature_gate = sym::my_feature_name;
}
```

Then, the lint will only fire if the user has the appropriate `#![feature(my_feature_name)]`.
Just beware that when it comes time to do crater runs testing the migration that the feature gate
will need to be removed.

Alternatively, you can implement an allow-by-default [migration lint] for an upcoming unstable
edition without a feature gate.
Although users may technically be able to enable the lint before the edition is stabilized, most