matrix-org / matrix-org/matrix-spec
Clarify what unstable and stable mean as words with respect to room versions
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
We should take the below context and put it somewhere, or change the verbiage to match the below expectations.
https://github.com/matrix-org/matrix-doc/pull/1773 went through a few iterations as to what to call this and track how useful/recommended a particular version is, but we seemingly settled on the current stable/unstable boolean without a whole lot of documentation to support it.
The stable-ness of a given room version is not generally affected by how stable a room version is, which is annoying. For example, if a room version were to regularly cause state resets (cough v1) we don't necessarily consider that "unstable". In fact, stability is more tied to what Matrix prefers the ecosystem to consist of and for major security vulnerabilities, such as if a room version could be exploited to gain unauthorized entry.
This had conversation context within the SCT years ago around the time of matrix-org/matrix-spec-proposals#1773 and focused on trying to determine what metrics we cared about for room version classifiers. Primarily, we care about what version is considered "best practice" for people use, which translates into today's recommended version, and how safe a room version is. We ended up boiling down 4 levels of upgrade noise to just 2, which got called stability:
- Upgrade is completely optional and opt-in, though risky because the version is not very mature
- Upgrade is completely optional and opt-in, but less risky because it's been tested a bit
- Upgrading is encouraged to stay current with the best practices
- Upgrade now because your room is vulnerable to attack
The first 3 states got rolled into "stable" as a classification, making upgrades entirely opt-in and optional. We also consciously lost the ability to recommend upgrades for best practices, though this is largely considered a UX problem and thus not a concern for the spec. The last state, 4, got called "unstable" with no wiggle room for how serious the upgrade is: unstable is vulnerable to attack (or at risk of the server not supporting it).
Something we also aimed to solve with the system is whether or not server implementations need to write in support for a given room version. In the end, we said servers should implement all stable versions and are not required to have any support for unstable versions. Stable versions are expected to be widely adopted by the ecosystem so servers should support them simply for the best interest of their user base, though if the environment allows then it's completely acceptable to not support a given room version. Unstable room versions on the other hand are considered completely unsafe to use for either security or development reasons (which is why all non-specified versions are considered unstable) - the server should only support unstable versions long enough for rooms to upgrade away from them. We by default chose the "recommended version" from the spec as the version to upgrade to away from unstable so there's at least a sense of what to do in the situation.
In practice, the client-side warnings have also evolved to accommodate a system of "development" and "vulnerable" for unstable versions, where they tend to consider spec-prefixed room versions as a binary vulnerable/not-vulnerable status (lining up with stable/unstable) and non-spec-prefixed room versions (MSCs) as unsafe but not vulnerable, understanding that they're typically used for development purposes. The clients in those cases will often still strongly recommend an upgrade away from the development version, but won't be as angry or alarming as vulnerable (spec-prefixed unstable) room versions.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review matrix-org/matrix-doc/pull/1773 and matrix-org/matrix-spec-proposals#1773 alongside the issue context. Identify where room-version stability classifications and upgrade guidance are documented, then clarify the meanings of stable and unstable, including server support and client warning expectations. Done means the terminology and guidance consistently match the intended classifications.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100