Have unstable/stable markers similar to rustc dev

[ShadowJonathan]

Like this: https://rustc-dev-guide.rust-lang.org/stability.html

rustc has markers like #[stable(...)] and #[unstable(...)], maybe it's interesting to replicate this?

Then we could annotate (parts of) API with #[stable(v = "1.1") (the API is stable since Matrix v1.1), #[unstable(msc=1234, rev="abc012")] (the API is unstable, but defined according to MSC1234, at commit abc012)

While for now this could serve as code markers for specific items, and documentation generation for item stability, in the future it might be possible to introduce custom lints and "matrix api levels" somewhere/somehow that could help an project building on rust to adhere to certain stability brackets?

---

Imagine this; you can define in your project configuration that;

• The project is intended to work with matrix v1.0-1.3.
• There are no unspecced endpoints allowed, but some exceptions are made for MSC X, Y and Z.

And lints will check if any usage code violates those rules.

[jplatte]

I like the idea of better tracking unstable features (which it feels like this issue is partially about?). But what do you mean by "stability brackets"?

[ShadowJonathan]

oh sorry, i was partially recalling something from MSC2844, which says something about the timetable for deprecation and removal for endpoints and features. i meant with "bracket" as a range of versions such a project then wishes to target, "Bracket: a category of people or things that are similar or fall between specified limits."

Yes, this issue is specifically inspired by the idea of "i wish i could track which MSC commit this API is based on", grabbed the rustc stability macros as an example, and realised it could apply further than just tracking unstable features.

[ShadowJonathan]

Furthermore, this would make it possible to simply annotate ruma with a crate feature such as "v1.2", "v1.3", "pre-spec", "latest-formal", and only have those options systematically available to use, and a compilation error if it's not.

The aforementioned markers (e.g. #[unstable(msc = 1234, rev = "abc012")], #[stable(spec_pr = 4567)], #[formal(doc_rev = "defg567"], #[released(new = "v1.0", depr = "v1.3", rem = "v1.4")) would simply expand to cfg annotations, only exposing the current object if the correct crate marker (v1.X, post-formal, pre-formal, unstable, etc.) are defined.

This would mainly help the project in the long term when maintaining multiple released matrix versions, and being able to systematically track changes specific to each of those. But it could also help with automatic doc generation ("This feature is experimental to MSC1234", "This feature is stable, but not released yet", "This feature was first released in matrix v1.X", "This feature is deprecated in v1.Y", etc.)