matrix-org / matrix-org/matrix-spec
Change "unstable" wording of spec versions to "unreleased"
- 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
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