When should I update to the latest edition?

[intgr]

I feel like the guide should answer this question, but it doesn't: when does it make sense to update my packages to a new edition? What are the downsides and other considerations? In particular, does it restrict the range of Rust versions that can be used to build my package?

In fact, after a significant amount of Googling I still don't have clear answers to these questions.

[rylev]

Have more clear guidance on this would indeed be a good idea. Here's my thoughts (and if they sound good to others, I can create a PR).

New Projects

The only consideration for new projects is minimum viable Rust version (MSRV). Since newer editions require a certain compiler version, deciding whether a new project should use the latest edition requires deciding what the minimum supported compiler version is. A vast majority of users use the latest stable version of the compiler (or a newer nightly version), so usually adopting a MSRV policy with a recent version isn't an issue.

Existing Projects

Existing projects must also consider what MSRV policy they want to adopt.

After that, it's usually a question of whether the cost of upgrading a project is worth it. I would wager that almost all upgrades to a new edition are trivial to do (using the automated tooling), but it is possible that there are some uses (particularly in macros) that aren't auto-migratable and may be less than trivial to migrate by hand. This should be easy to see, by running the migration tool and checking if the migrate produced a working project (by running cargo test) .

Conclusion

Other than those issues I believe there are no downsides to upgrading to a new edition so assuming those issues do not apply to your project, you should go ahead and upgrade. Almost all projects use the latest edition (Rust 2018 had over a 99% adoption rate) and so contributors are likely expecting that a project uses the latest edition. Of course, this becomes more true the longer away from an edition release you are.

[intgr]

Thanks! I think it's worth stressing that bumping the edition number breaks compilation with older Rust versions, even if the project does not rely on any of the new features.

And maybe add a table with editions, minimum Rust versions and their release dates. Although that would duplicate content on per-edition pages.

[nikomatsakis]

I agree with @rylev -- the only reason I can see not to upgrade is MSRV. I would like to see people upgrade in general, but of course the main reason to upgrade would be to get access to the "nicer Rust" that it provides (sometimes there are new features that build directly on syntactic space reserved by the edition, of course).