Document which rustdoc format versions are supported

[obi1kenobi]

With #126 and #131, we should shortly be able to support multiple rustdoc format versions simultaneously. But how many of them, and which ones?

The downside to supporting too many rustdoc format versions is bloat in the executable, longer compile times, and a bit more work when expanding the schema size and publishing updated Trustfall adapters for each format version.

• Guaranteed support: current and previous stable Rust
• Expected support: latest nightly — we might not support it on day 1 but we should try to add support quickly
• Best-effort only: versions between current stable and latest nightly — these are easy to support if we haven't expanded the size of the schema

Any concerns? Any other versions that are worth supporting? Any you'd remove from this list?

[epage]

I think

• MSRV to latest stable
• latest beta (to make sure we are ready on day 1 of a stable release)

For nightly, the main question is what is the goal for supporting it. Just so users can be using nightly be default? That would mean an unspecified number of very specific nightlies because there is little reason for people to keep nightly on the float.

[obi1kenobi]

Agreed on MSRV to latest stable + latest beta.

Should we be worried about folks who always build on nightly by default? Is it better to ~never support the use case vs "maybe" supporting it on a best-effort basis?

Here's a specific example I'd love your thoughts on:

• Say stable uses format number X, beta uses X+1, nightly currently has X+2 and hasn't changed in a little while.
• We've already added support for X+2 in anticipation of it being shipped in the beta.
• Right before the beta is published, the rustdoc format version is changed to X+3. We add support for X+3 as well.
• The previous X+2 format still works, and we could support it as well if we so chose (we have the code!). It's still in the interval between latest stable and latest nightly even though it isn't the beta's format.

In this case, when should we drop support for the X+2 format? Options: (a) Immediately as soon as it's clear it won't ship in the beta, since it won't ever be in any stable Rust. (b) As soon as X+3 makes it to beta, since the current nightly at the time is guaranteed to use X+3 or above. (c) As soon as X+3 makes it to stable, since X+2 is no longer in the interval between latest stable and latest nightly. (d) Something else?

[epage]

Should we be worried about folks who always build on nightly by default? Is it better to ~never support the use case vs "maybe" supporting it on a best-effort basis?

My concern is if someone's default is nightly then that will be a specific version that could range be within a 6 month range. It'd be great if we knew how often nightly folks updated.

In this case, when should we drop support for the X+2 format?

I could see us purging versions on an as-need basis. We'll want to document what stable each version is associated with so we know what we can purge.

[obi1kenobi]

Let's go with MSRV to current stable + current beta in the "guaranteed" bucket and "some nightlies might work but no promises / purge as needed"?

It might be too much overhead to maintain docs around which nightlies happen to use supported format versions, but we can easily document which JSON format versions are supported (so nightly users can check their local installation), and we already have decent error messages if an unsupported version is used.