matrix-org / matrix-org/matrix-spec

Change "unstable" wording of spec versions to "unreleased"

Open
#976 4 comments 0 reactions 0 assignees View on GitHub
aesthetic
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

Currently, https://spec.matrix.org/unstable/ tracks `main`, while positioning itself as "unstable" with the URL, and with the snippet at the top of the pages;

```
You're looking at an unstable version of this specification. Unstable specifications may change at any time without notice.
```

I believe this wording/naming can be softened to unreleased, as often enough the wording in the specification is stable; meaning that all MSCs backing the behaviour changes have finalised, and the only changes at that moment would be fixes to fill oversights.

Consequently, I'm also asking to change the wording of "Switch to the current stable release." to "Switch to the latest release", as that makes more sense.

The definition of stable and unstable is pointed to a lot around the spec, specifically around the proposal process, where an MSC is "stable" once it has passed FCP. So, confusion can occur if someone's "stable" MSC enters an "unstable" specification, is their MSC "unstable" by extension as well? The bending of the definition may be unclear or not easily inferred, as the exact range of "stability" guaranteed by the "stable" definition changes a lot around the spec this way.

I'm aware that the spec can release sub-releases, such as `v1.2-alpha` and such, but even then, i still think "released"/"unreleased" fits this dynamic better than "stable"/"unstable".

Contributor guide

Open the contributing guide

Research direction

Start at the https://spec.matrix.org/unstable/ pages and search the specification source or templates for the quoted “unstable” notice and “Switch to the current stable release.” text. Check whether the wording appears in multiple generated pages, then verify that the pages consistently say “unreleased” and “Switch to the latest release”.

Written by the indexing model from the issue text.

Assessment

Tech stack
html
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.