search

matrix-org / matrix-spec

The Matrix protocol specification
Apache License 2.0
188 stars 94 forks source link

Clarification of invite->knock introduced in 1.10 should be at least a warning on older rendered spec versions #1777

Open MTRNord opened 6 months ago

MTRNord commented 6 months ago

Link to problem area:

Issue

https://github.com/matrix-org/matrix-spec/issues/1717 introduced a change to room versions introduced in earlier spec versions retroactively. While this in general is fine due to the versioning of Spec the Room versions are explicitly building upon their own room version versioning schema. This means that there now are at least Spec 1.9 and Spec 1.10 saying different rules on the room versions 7, 8, 10 and 11.

In normal changes to S-S api or C-S Api updating the spec version would be sufficient. For Room Versions it is not as Matrix spec these days doesnt exist in isolation of the wider internet. Which means some projects like TI-Messenger are pinning their specs on top of specific matrix spec versions instead of running latest at all times. This means anyone relying on 1.9 (or others with the old rules) will now run different room versions than the rest of the ecosystem as these pinnings usually have a statement of "You can use newer spec if they are backwards compatible" (this is what TI-Messenger spec for example said when they pinned to 1.3). However the clarification here is not backwards compatible meaning people would not be using the same room versions as the rest of the ecosystem.

Ideally it would be a good idea to at least add warning boxes to the older affected spec versions that 1.10 had a crucial fix to these versions which should be applied. I do understand that this clarification technically is following process of the way spec versioning goes. But sadly this is somewhat of an edgecase of how room versioning and spec versioning interact with each other and they technically are not moving at the same pace.

richvdh commented 5 months ago

@MTRNord please could you link to the areas of the spec that you are concerned about? It's very hard to understand a wall of text without any reference points.

turt2live commented 5 months ago

From the text alone, I'm not sure this is something we want to do. We already have warnings that old versions are old, and I don't think that individual sections of the spec need that warning too. We may consider making the old version warning sticky/floating though, causing it to always be visible.

This is aside from the massive amount of effort it takes to update an old version of the spec. At time of release, when all the dependencies are known to be working, we compile the spec's "historical" version. When the next release happens, we download that artifact and replace the spec with the historical version. We do this because trying to go back 3-6 months (or 3 years in the case of this issue's proposal) rarely ever works due to changes in dependencies, build environment, etc.