From 7f59715369d78dd03d60c3b41bd42f911414c1f0 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 6 Oct 2025 09:58:50 +0200 Subject: [PATCH 1/4] Clarify vendor prefixing requirements Signed-off-by: Johannes Marbach --- .../internal/newsfragments/2222.clarification | 1 + content/proposals.md | 123 +++++++++++------- 2 files changed, 76 insertions(+), 48 deletions(-) create mode 100644 changelogs/internal/newsfragments/2222.clarification diff --git a/changelogs/internal/newsfragments/2222.clarification b/changelogs/internal/newsfragments/2222.clarification new file mode 100644 index 00000000..188d64bb --- /dev/null +++ b/changelogs/internal/newsfragments/2222.clarification @@ -0,0 +1 @@ +Clarify vendor prefixing requirements. diff --git a/content/proposals.md b/content/proposals.md index eb7fd3da..2d6a5d3f 100644 --- a/content/proposals.md +++ b/content/proposals.md @@ -408,41 +408,9 @@ development or testing data. that a particular MSC works) do not have to follow this process. 1. Have an idea for a feature. -1. Implement the feature using unstable endpoints, vendor prefixes, and - unstable feature flags as appropriate. - - When using unstable endpoints, they MUST include a vendor - prefix. For example: - `/_matrix/client/unstable/com.example/login`. Vendor prefixes - throughout Matrix always use the Java package naming convention. - The MSC for the feature should identify which preferred vendor - prefix is to be used by early adopters. - - Note that unstable namespaces do not automatically inherit - endpoints from stable namespaces: for example, the fact that - `/_matrix/client/r0/sync` exists does not imply that - `/_matrix/client/unstable/com.example/sync` exists. - - If the client needs to be sure the server supports the feature, - an unstable feature flag that MUST be vendor prefixed is to be - used. This kind of flag shows up in the `unstable_features` - section of `/versions` as, for example, `com.example.new_login`. - The MSC for the feature should identify which preferred feature - flag is to be used by early adopters. - - When using this approach correctly, the implementation can - ship/release the feature at any time, so long as the - implementation is able to accept the technical debt that results - from needing to provide adequate backwards and forwards - compatibility. The implementation MUST support the flag (and - server-side implementation) disappearing and be generally safe - for users. Note that implementations early in the MSC review - process may also be required to provide backwards compatibility - with earlier editions of the proposal. - - If the implementation cannot support the technical debt (or if - it's impossible to provide forwards/backwards compatibility - - e.g. a user authentication change which can't be safely rolled - back), the implementation should not attempt to implement the - feature and should instead wait for a spec release. - - If at any point after early release, the idea changes in a - backwards-incompatible way, the feature flag should also change - so that implementations can adapt as needed. +1. Implement the feature using [unstable endpoints, vendor prefixes, and + unstable feature flags](#unstable-endpoints-features-and-vendor-prefixes) + as appropriate. 1. In parallel, or ahead of implementation, open an MSC and solicit review per above. 1. Before FCP can be called, the Spec Core Team will require evidence @@ -452,10 +420,7 @@ that a particular MSC works) do not have to follow this process. forwards/backwards compatibility concerns mentioned here. 1. The FCP process is completed, and assuming nothing is flagged the MSC lands. -1. Implementations can now switch to using stable prefixes - (for example, for an endpoint, moving from - `/unstable/org.matrix.mscxxxx/frobnicate` - to `/v1/frobnicate`), assuming that the change +1. Implementations can now switch to using stable prefixes, assuming that the change is backwards compatible with older implementations. In the rare occasion where backwards compatibility is not possible without a new spec release, implementations should continue to use unstable prefixes. @@ -471,13 +436,6 @@ that a particular MSC works) do not have to follow this process. started supporting the new spec release, some noise should be raised in the general direction of the implementation. -{{% boxes/note %}} -MSCs MUST still describe what the stable endpoints/feature looks like -with a note towards the bottom for what the unstable feature -flag/prefixes are. For example, an MSC would propose `/_matrix/client/r0/new/endpoint`, not `/_matrix/client/unstable/ -com.example/new/endpoint`. -{{% /boxes/note %}} - In summary: - Implementations MUST NOT use stable endpoints before the MSC has @@ -489,14 +447,83 @@ In summary: - Implementations SHOULD be wary of the technical debt they are incurring by moving faster than the spec. - The vendor prefix is chosen by the developer of the feature, using - the Java package naming convention. The foundation's preferred - vendor prefix is `org.matrix`. + the Java package naming convention. - The vendor prefixes, unstable feature flags, and unstable endpoints should be included in the MSC, though the MSC MUST be written in a way that proposes new stable endpoints. Typically this is solved by a small table at the bottom mapping the various values from stable to unstable. +#### Unstable endpoints, features and vendor prefixes + +Unstable endpoints MUST use `/unstable` as the endpoint version and a +vendor prefix in Java package naming format. For example: +`/_matrix/client/unstable/org.matrix.mscxxxx/login`. The foundation's +preferred vendor prefix is `org.matrix`. + +Note that unstable namespaces do not automatically inherit endpoints from +stable namespaces: for example, the fact that `/_matrix/client/v3/sync` +exists does not imply that `/_matrix/client/unstable/org.matrix.mscxxxx/sync` +exists. + +Vendor prefixes MUST also be used for: + +- New parameters on existing endpoints. For example: + `/_matrix/client/v3/publicRooms?org.matrix.mscxxxx.ordered_by=member_count`. +- New properties in existing JSON objects. For example: + + ```json + { + "avatar_url": "mxc://matrix.org/SDGdghriugerRg", + "displayname": "Alice Margatroid", + "org.matrix.mscxxxx.phone": [{ + "type": "landline", + "number": "+1-206-555-7000" + }], + ... + } + ``` +- New values for existing parameters or properties. For example: + + ```json + { + "errcode": "ORG.MATRIX.MSCXXXX.M_INVALID_EMAIL", + "error": "The email address you provided is invalid." + } + ``` + +If the client needs to be sure the server supports the feature, an +unstable feature flag that MUST also be vendor prefixed is to be used. +This flag shows up in the `unstable_features` section of +[`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions) +as, for example, `org.matrix.mscxxxx.new_login`. + +{{% boxes/note %}} +MSCs MUST still describe what the stable endpoints/feature looks like +with a note towards the bottom for what the unstable feature +flag/prefixes are. For example, an MSC would propose `/_matrix/client/v1/new/endpoint`, +not `/_matrix/client/unstable/org.matrix.mscxxxx/new/endpoint`. +{{% /boxes/note %}} + +When using this approach correctly, the implementation can release +the feature at any time, so long as the implementation is able to +accept the technical debt that results from needing to provide +adequate backwards and forwards compatibility. The implementation +MUST support the flag (and server-side implementation) disappearing +and be generally safe for users. Note that implementations early in +the MSC review process may also be required to provide backwards +compatibility with earlier editions of the proposal. + +If the implementation cannot support the technical debt (or if it's +impossible to provide forwards/backwards compatibility - e.g. a user +authentication change which can't be safely rolled back), the +implementation should not attempt to implement the feature and should +instead wait for a spec release. + +If at any point after early release, the idea changes in a +backwards-incompatible way, the feature flag should also change so +that implementations can adapt as needed. + ### Placeholder MSCs Some proposals may contain security-sensitive or private context which can't be From 35eb6e1d2b5fbf7b02e9e8495d29ab355f8886e9 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 7 Oct 2025 08:37:58 +0200 Subject: [PATCH 2/4] Clarify that org.matrix is reserved Signed-off-by: Johannes Marbach --- content/proposals.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/content/proposals.md b/content/proposals.md index 2d6a5d3f..481a223b 100644 --- a/content/proposals.md +++ b/content/proposals.md @@ -458,25 +458,31 @@ In summary: Unstable endpoints MUST use `/unstable` as the endpoint version and a vendor prefix in Java package naming format. For example: -`/_matrix/client/unstable/org.matrix.mscxxxx/login`. The foundation's -preferred vendor prefix is `org.matrix`. +`/_matrix/client/unstable/com.example.mscxxxx/login`. + +{{% boxes/note %}} +Proposal authors operating with a Matrix.org Foundation mandate SHOULD use +a vendor prefix within the `org.matrix` namespace. This namespace is otherwise +restricted. Authors who don't own a domain MAY use the `com.github` namespace +instead. +{{% /boxes/note %}} Note that unstable namespaces do not automatically inherit endpoints from stable namespaces: for example, the fact that `/_matrix/client/v3/sync` -exists does not imply that `/_matrix/client/unstable/org.matrix.mscxxxx/sync` +exists does not imply that `/_matrix/client/unstable/com.example.mscxxxx/sync` exists. Vendor prefixes MUST also be used for: - New parameters on existing endpoints. For example: - `/_matrix/client/v3/publicRooms?org.matrix.mscxxxx.ordered_by=member_count`. + `/_matrix/client/v3/publicRooms?com.example.mscxxxx.ordered_by=member_count`. - New properties in existing JSON objects. For example: ```json { "avatar_url": "mxc://matrix.org/SDGdghriugerRg", "displayname": "Alice Margatroid", - "org.matrix.mscxxxx.phone": [{ + "com.example.mscxxxx.phone": [{ "type": "landline", "number": "+1-206-555-7000" }], @@ -487,7 +493,7 @@ Vendor prefixes MUST also be used for: ```json { - "errcode": "ORG.MATRIX.MSCXXXX.M_INVALID_EMAIL", + "errcode": "COM.EXAMPLE.MSCXXXX.M_INVALID_EMAIL", "error": "The email address you provided is invalid." } ``` @@ -496,13 +502,13 @@ If the client needs to be sure the server supports the feature, an unstable feature flag that MUST also be vendor prefixed is to be used. This flag shows up in the `unstable_features` section of [`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions) -as, for example, `org.matrix.mscxxxx.new_login`. +as, for example, `com.example.mscxxxx.new_login`. {{% boxes/note %}} MSCs MUST still describe what the stable endpoints/feature looks like with a note towards the bottom for what the unstable feature flag/prefixes are. For example, an MSC would propose `/_matrix/client/v1/new/endpoint`, -not `/_matrix/client/unstable/org.matrix.mscxxxx/new/endpoint`. +not `/_matrix/client/unstable/com.example.mscxxxx/new/endpoint`. {{% /boxes/note %}} When using this approach correctly, the implementation can release From ffc8c8edd334aafca4d2744c28561900add7a943 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 7 Oct 2025 18:23:18 +0200 Subject: [PATCH 3/4] com.github -> Io.github Co-authored-by: Alexey Rusakov --- content/proposals.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/proposals.md b/content/proposals.md index 481a223b..4e145998 100644 --- a/content/proposals.md +++ b/content/proposals.md @@ -463,7 +463,7 @@ vendor prefix in Java package naming format. For example: {{% boxes/note %}} Proposal authors operating with a Matrix.org Foundation mandate SHOULD use a vendor prefix within the `org.matrix` namespace. This namespace is otherwise -restricted. Authors who don't own a domain MAY use the `com.github` namespace +restricted. Authors who don't own a domain MAY use the `io.github` namespace instead. {{% /boxes/note %}} From 1baf93caf54b15b7ef76586084a6cecdc4977097 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 7 Oct 2025 18:23:45 +0200 Subject: [PATCH 4/4] Add blank line Co-authored-by: Alexey Rusakov --- content/proposals.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/proposals.md b/content/proposals.md index 4e145998..47fb112b 100644 --- a/content/proposals.md +++ b/content/proposals.md @@ -489,6 +489,7 @@ Vendor prefixes MUST also be used for: ... } ``` + - New values for existing parameters or properties. For example: ```json