I hit an interesting issue recently; in a crate I maintain, we have a cargo feature which enables and uses the unstable
external_doc feature so that docs.rs can load doc comments from a README.md. This works because docs.rs runs against nightly.
This feature got removed because a replacement got stabilised. This is great - the stabilised feature is excellent, and a very clean answer to the problem. I'm looking forward to deleting our old code and using the new form.
However, the replacement uses syntax which was not previously accepted by the parser, and so cannot be conditionally enabled (i.e. we cannot
#![cfg_attr(feature = "external_doc", doc = include_str!("../README.md"))]). Worse than that, the code we want to conditionally enable is in an inner attribute, so we can't do something sneaky like conditionally load a file containing the inner attribute depending on compiler version.
This puts us in a slightly tricky position. As things currently stand, I don't think we can reasonably release new versions of the crate until after the next stable release. The old way has been removed, so if we release our existing code, docs.rs will fail to generate documentation for our crate - this is unfortunate. If we replace the old way with the new one, our crate won't compile on stable, because the replacement feature is currently only on beta - this is a hard blocker. There are hacks we can perform, but they're definitely hacks.
You could argue that we made this mess for ourselves by choosing to pull in an unstable feature, but it feels like it would perhaps be considerate in the future to delay removing features until the replacement hits stable, rather than just blocking on getting merged into nightly - at least where this doesn't pose significant problems for the implementation. Could we perhaps aim for this as a best-effort guideline?
(In the mean time, I'd love it if we reverted the feature removal and re-landed it in three weeks time when 1.54.0 hits stable...)