From 390bee40aeec053d2835208d48a8c609f3cc01a7 Mon Sep 17 00:00:00 2001 From: Valere Date: Thu, 3 Jun 2021 12:09:26 +0200 Subject: [PATCH 01/10] Spaces top level order --- proposals/3230-spaces_top_level_order | 92 +++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 proposals/3230-spaces_top_level_order diff --git a/proposals/3230-spaces_top_level_order b/proposals/3230-spaces_top_level_order new file mode 100644 index 00000000000..1de605b3e6b --- /dev/null +++ b/proposals/3230-spaces_top_level_order @@ -0,0 +1,92 @@ +# MSC3230: User defined top level spaces ordering + +Currently, Spaces as defined per [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772) do not define an explicit order for top level spaces. Current implementations ere ordering based on the lexicographic order of the roomIds. + +As requested by a lot of users, it would be very convenient to be able to re-order top level spaces. + +The ordering is per user and should be persisted and synced across the user's devices. + +This MSC only concerns top level space ordering as subspace ordering is defined in the space as per m.space.child event. + +## Proposal + +The ordering information should be stored using room [`account_data`](https://matrix.org/docs/spec/client_server/latest#id125) + + +Order is stored using existing [Room Tagging](https://matrix.org/docs/spec/client_server/latest#room-tagging) mecanism. + +> The tags on a room are received as single m.tag event in the account_data section of a room. The content of the m.tag event is a tags key whose value is an object mapping the name of each tag to another object. +> +> The JSON object associated with each tag gives information about the tag, e.g how to order the rooms with a given tag. + +```` +{ + "content": { + "tags": { + "m.space": { + "order": 0.9 + } + } + }, + "type": "m.tag" +} +```` + +As defined per `room tagging`ordering information is given under the order key as a number between 0 and 1. The numbers are compared such that 0 is displayed first. Therefore a room with an order of 0.2 would be displayed before a room with an order of 0.7. If a room has a tag without an order key then it should appear after the rooms with that tag that have an order key, fallbacking then to roomID lexical order. + + +## Client recommendations: + +After moving a space (e.g via DnD), client should limit the number of room account data update. For example if the space is moved between two other spaces, just update the moved space order by taking the midpoint between the enclosing order. + +When the lower sibling has no order, a strategy could be to re-order the undefined one starting from the last ordered one by adding steps defined by number of nodes. Also client should avoid setting 0 and 1 order. + +=> INCLUDE HERE DETAILED ALGORITHM? + + +## Future considerations + +__Space Pinning__: The room tag usage could be extended and define `u.space.favourite` or `u.space.lowpriority`` + + +__Space Folder__: In order to save vertical space spaces with same order could be represented as a single entry in the panel represented as a folder on clients? + + +## Alternatives + +It's not clear whether this setting should be using global vs room scope. + +Order could be stored in a global scope account as an array of roomID in the `org.matrix.mscXXX.space.order` type. +```` +{ + "type": "org.matrix.mscXXX.space.order", + "content": { + "order": [ + "!GDoOXUnhorabeOhHur:matrix.org", + "!ERioTVWSdvArJzumhm:foo.bar", + "!AZozoWghOYSIAzerOIf:example.org", + "!uZvykTONFkrkzGUFVE:mozilla.org", + "!TfGEAMfGlIFILPqKYwQ:matrix.org", + "!TaFfBCfZQRjDkrTvbDb:matrix.org" + ] + } +} +```` + +This alternative has been discarded has it won't scale, could reach event content size limit, and is less flexible as a way to define order compared to [0,1]. + + + + +## Potential issues + +## Privacy considerations + +## Unstable prefix + +The following mapping will be used for identifiers in this MSC during development: + + +Proposed final identifier | Purpose | Development identifier +------------------------------- | ------- | ---- +`m.space` | event type | `m.msc3230_space` \ No newline at end of file From d85ac46915242cc35f751da445101e742f00b075 Mon Sep 17 00:00:00 2001 From: Valere Date: Thu, 3 Jun 2021 12:12:33 +0200 Subject: [PATCH 02/10] Update proposals/3230-spaces_top_level_order Co-authored-by: Michael Telatynski <7t3chguy@googlemail.com> --- proposals/3230-spaces_top_level_order | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3230-spaces_top_level_order b/proposals/3230-spaces_top_level_order index 1de605b3e6b..f5de5e79760 100644 --- a/proposals/3230-spaces_top_level_order +++ b/proposals/3230-spaces_top_level_order @@ -1,6 +1,6 @@ # MSC3230: User defined top level spaces ordering -Currently, Spaces as defined per [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772) do not define an explicit order for top level spaces. Current implementations ere ordering based on the lexicographic order of the roomIds. +Currently, Spaces as defined per [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772) do not define an explicit order for top level spaces. Current implementations are ordering based on the lexicographic order of the roomIds. As requested by a lot of users, it would be very convenient to be able to re-order top level spaces. @@ -89,4 +89,4 @@ The following mapping will be used for identifiers in this MSC during developmen Proposed final identifier | Purpose | Development identifier ------------------------------- | ------- | ---- -`m.space` | event type | `m.msc3230_space` \ No newline at end of file +`m.space` | event type | `m.msc3230_space` From 52b2f106fb6dc0c20e275c161bf2be7ce381053e Mon Sep 17 00:00:00 2001 From: Valere Date: Thu, 3 Jun 2021 12:15:39 +0200 Subject: [PATCH 03/10] missing md ext --- ...3230-spaces_top_level_order => 3230-spaces_top_level_order.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{3230-spaces_top_level_order => 3230-spaces_top_level_order.md} (100%) diff --git a/proposals/3230-spaces_top_level_order b/proposals/3230-spaces_top_level_order.md similarity index 100% rename from proposals/3230-spaces_top_level_order rename to proposals/3230-spaces_top_level_order.md From 5d3e169fcee47be1e8ca1824c61263cf01cedcbc Mon Sep 17 00:00:00 2001 From: Valere Date: Thu, 3 Jun 2021 14:53:47 +0200 Subject: [PATCH 04/10] Review updates --- proposals/3230-spaces_top_level_order.md | 69 ++++++++++++++++-------- 1 file changed, 48 insertions(+), 21 deletions(-) diff --git a/proposals/3230-spaces_top_level_order.md b/proposals/3230-spaces_top_level_order.md index f5de5e79760..4135968ea08 100644 --- a/proposals/3230-spaces_top_level_order.md +++ b/proposals/3230-spaces_top_level_order.md @@ -12,48 +12,50 @@ This MSC only concerns top level space ordering as subspace ordering is defined The ordering information should be stored using room [`account_data`](https://matrix.org/docs/spec/client_server/latest#id125) +Order is saved by using a new room account data of type `m.space_order` -Order is stored using existing [Room Tagging](https://matrix.org/docs/spec/client_server/latest#room-tagging) mecanism. - -> The tags on a room are received as single m.tag event in the account_data section of a room. The content of the m.tag event is a tags key whose value is an object mapping the name of each tag to another object. -> -> The JSON object associated with each tag gives information about the tag, e.g how to order the rooms with a given tag. +` PUT /_matrix/client/r0/user/{userId}/rooms/{roomId}/account_data/m.space.order` ```` { + "type": "m.space_order", "content": { - "tags": { - "m.space": { - "order": 0.9 - } - } - }, - "type": "m.tag" + "order": "..." + } } ```` -As defined per `room tagging`ordering information is given under the order key as a number between 0 and 1. The numbers are compared such that 0 is displayed first. Therefore a room with an order of 0.2 would be displayed before a room with an order of 0.7. If a room has a tag without an order key then it should appear after the rooms with that tag that have an order key, fallbacking then to roomID lexical order. +Where `order` is a string that will be compared using lexicographic order. Spaces with no order should appear last and be ordered using the roomID. + +Order is defined as a `string` and not a `float` as in room tags, as recommanded because it was not very successful. + ## Client recommendations: -After moving a space (e.g via DnD), client should limit the number of room account data update. For example if the space is moved between two other spaces, just update the moved space order by taking the midpoint between the enclosing order. +After moving a space (e.g via DnD), client should limit the number of room account data update. +For example if the space is moved between two other spaces, just update the moved space order by appending a new character to the previous space order string -When the lower sibling has no order, a strategy could be to re-order the undefined one starting from the last ordered one by adding steps defined by number of nodes. Also client should avoid setting 0 and 1 order. +Re numbering (i.e change all spaces `m.space.order` account data) should be avoided as much as possible, as the updates might not be atomic for other clients and would makes spaces jump around. -=> INCLUDE HERE DETAILED ALGORITHM? +## Potential issues +Spreading the order information across all spaces account data is making order changes not atomic. -## Future considerations +Order string could grow infinitly and reach a hard limit, it might be needed to re-number when order string are too big. -__Space Pinning__: The room tag usage could be extended and define `u.space.favourite` or `u.space.lowpriority`` +## Future considerations + +__Space Pinning__: The room `m.space_order` content could be extended by adding categories like `pinned` -__Space Folder__: In order to save vertical space spaces with same order could be represented as a single entry in the panel represented as a folder on clients? +__Space Folder__: In order to save vertical space, content could be extended to define folders and space with same folder could be represented as a single entry in the space pannel. On tap would expand the pannel. ## Alternatives +__Global Scope Account Data__ + It's not clear whether this setting should be using global vs room scope. Order could be stored in a global scope account as an array of roomID in the `org.matrix.mscXXX.space.order` type. @@ -73,8 +75,33 @@ Order could be stored in a global scope account as an array of roomID in the `or } ```` -This alternative has been discarded has it won't scale, could reach event content size limit, and is less flexible as a way to define order compared to [0,1]. +This alternative has been discarded as it won't scale, could reach event content size limit, and is less flexible as a way to define order compared to [0,1]. + +__Room Tags__ + + +Order is stored using existing [Room Tagging](https://matrix.org/docs/spec/client_server/latest#room-tagging) mecanism. + +> The tags on a room are received as single m.tag event in the account_data section of a room. The content of the m.tag event is a tags key whose value is an object mapping the name of each tag to another object. +> +> The JSON object associated with each tag gives information about the tag, e.g how to order the rooms with a given tag. + +```` +{ + "content": { + "tags": { + "m.space": { + "order": 0.9 + } + } + }, + "type": "m.tag" +} +```` + +As defined per `room tagging`ordering information is given under the order key as a number between 0 and 1. The numbers are compared such that 0 is displayed first. Therefore a room with an order of 0.2 would be displayed before a room with an order of 0.7. If a room has a tag without an order key then it should appear after the rooms with that tag that have an order key, fallbacking then to roomID lexical order. +This alternative has been discarded becaused perceived as confusing in regards of tags intentions. @@ -89,4 +116,4 @@ The following mapping will be used for identifiers in this MSC during developmen Proposed final identifier | Purpose | Development identifier ------------------------------- | ------- | ---- -`m.space` | event type | `m.msc3230_space` +`m.space_order` | event type | `org.matrix.msc3230.space_order` From 9ca2a28ea7202ee9062401538dcb8b1f8f266400 Mon Sep 17 00:00:00 2001 From: Valere Date: Thu, 3 Jun 2021 14:54:42 +0200 Subject: [PATCH 05/10] fix typo --- proposals/3230-spaces_top_level_order.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3230-spaces_top_level_order.md b/proposals/3230-spaces_top_level_order.md index 4135968ea08..23365e26efd 100644 --- a/proposals/3230-spaces_top_level_order.md +++ b/proposals/3230-spaces_top_level_order.md @@ -14,7 +14,7 @@ The ordering information should be stored using room [`account_data`](https://ma Order is saved by using a new room account data of type `m.space_order` -` PUT /_matrix/client/r0/user/{userId}/rooms/{roomId}/account_data/m.space.order` +` PUT /_matrix/client/r0/user/{userId}/rooms/{roomId}/account_data/m.space_order` ```` { From a2680854d6b437c16b7fe47972bdbac57beef793 Mon Sep 17 00:00:00 2001 From: Valere Date: Fri, 4 Jun 2021 15:18:37 +0200 Subject: [PATCH 06/10] Update proposals/3230-spaces_top_level_order.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Erkin Alp Güney --- proposals/3230-spaces_top_level_order.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/3230-spaces_top_level_order.md b/proposals/3230-spaces_top_level_order.md index 23365e26efd..6568ba75b24 100644 --- a/proposals/3230-spaces_top_level_order.md +++ b/proposals/3230-spaces_top_level_order.md @@ -1,6 +1,8 @@ # MSC3230: User defined top level spaces ordering -Currently, Spaces as defined per [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772) do not define an explicit order for top level spaces. Current implementations are ordering based on the lexicographic order of the roomIds. +Currently, Spaces as defined per [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772) +do not define an explicit order for top level spaces. Current implementations are ordering based +on the lexicographic order of the roomIds. As requested by a lot of users, it would be very convenient to be able to re-order top level spaces. From 835d6a338b8818733a97acef91be0a5f475622f2 Mon Sep 17 00:00:00 2001 From: Valere Date: Fri, 11 Jun 2021 11:10:14 +0200 Subject: [PATCH 07/10] Added details on order and mid point computation + Cleaning / line wrap / feedbacks --- proposals/3230-spaces_top_level_order.md | 62 ++++++++++++++++-------- 1 file changed, 43 insertions(+), 19 deletions(-) diff --git a/proposals/3230-spaces_top_level_order.md b/proposals/3230-spaces_top_level_order.md index 6568ba75b24..17a87b661f7 100644 --- a/proposals/3230-spaces_top_level_order.md +++ b/proposals/3230-spaces_top_level_order.md @@ -8,11 +8,12 @@ As requested by a lot of users, it would be very convenient to be able to re-ord The ordering is per user and should be persisted and synced across the user's devices. -This MSC only concerns top level space ordering as subspace ordering is defined in the space as per m.space.child event. +This MSC only concerns top level space ordering as subspace ordering is defined in the space +as per m.space.child event. ## Proposal -The ordering information should be stored using room [`account_data`](https://matrix.org/docs/spec/client_server/latest#id125) +The ordering information should be stored using room [`account_data`](https://matrix.org/docs/spec/client_server/r0.6.1#id125) Order is saved by using a new room account data of type `m.space_order` @@ -27,32 +28,54 @@ Order is saved by using a new room account data of type `m.space_order` } ```` -Where `order` is a string that will be compared using lexicographic order. Spaces with no order should appear last and be ordered using the roomID. +Where `order` is a string that will be compared using lexicographic order. Spaces with +no order should appear last and be ordered using the roomID. -Order is defined as a `string` and not a `float` as in room tags, as recommanded because it was not very successful. +`orders` which are not strings, or do not consist solely of ascii characters in the range \x20 (space) to \x7E (~), +or consist of more than 50 characters, are forbidden and the field should be ignored if received.) +Order is defined as a `string` and not a `float` as in room tags, as recommended because it was +not very successful (Caused infinite problems when we first did it due to truncation and rounding +and ieee representation quirks). +__Recommended algorithm to compute mid points:__ + +In order to find mid points between two orders strings, the `order` string can be considered as +a base N number where N is the length of the allowed alphabet. So the string can be converted +to a base 10 number for computation and mid point computation, then converted back to base N. + +In order to compare strings of different sizes, the shortest string should be padded +with \x20 (space) to \x7E (~). ## Client recommendations: After moving a space (e.g via DnD), client should limit the number of room account data update. -For example if the space is moved between two other spaces, just update the moved space order by appending a new character to the previous space order string +For example if the space is moved between two other spaces with orders, just update the moved space order by +computing a mid point between the surrounding orders. -Re numbering (i.e change all spaces `m.space.order` account data) should be avoided as much as possible, as the updates might not be atomic for other clients and would makes spaces jump around. +If the space is moved after a space with no order, all the previous spaces should be then ordered, +and the computed orders should be choosen so that there is enough gaps in between them to facilitate future +re-order. + +Re numbering (i.e change all spaces `m.space.order` account data) should be avoided as much as possible, +as the updates might not be atomic for other clients and would makes spaces jump around. ## Potential issues Spreading the order information across all spaces account data is making order changes not atomic. -Order string could grow infinitly and reach a hard limit, it might be needed to re-number when order string are too big. +Order string could grow infinitly and reach a hard limit, it might be needed to re-number +when order string are too big. ## Future considerations -__Space Pinning__: The room `m.space_order` content could be extended by adding categories like `pinned` +__Space Pinning__: The room `m.space_order` content could be extended by adding categories like `pinned`. -__Space Folder__: In order to save vertical space, content could be extended to define folders and space with same folder could be represented as a single entry in the space pannel. On tap would expand the pannel. +__Space Folder__: In order to save vertical space, content could be extended to define folders +and space with same folder could be represented as a single entry in the space pannel. +On tap would expand the pannel. ## Alternatives @@ -77,16 +100,20 @@ Order could be stored in a global scope account as an array of roomID in the `or } ```` -This alternative has been discarded as it won't scale, could reach event content size limit, and is less flexible as a way to define order compared to [0,1]. +This alternative has been discarded as it won't scale, could reach event content size limit, and is +less flexible as a way to define order compared to [0,1]. __Room Tags__ Order is stored using existing [Room Tagging](https://matrix.org/docs/spec/client_server/latest#room-tagging) mecanism. -> The tags on a room are received as single m.tag event in the account_data section of a room. The content of the m.tag event is a tags key whose value is an object mapping the name of each tag to another object. +> The tags on a room are received as single m.tag event in the account_data section of a room. +The content of the m.tag event is a tags key whose value is an object mapping the name of each tag +to another object. > -> The JSON object associated with each tag gives information about the tag, e.g how to order the rooms with a given tag. +> The JSON object associated with each tag gives information about the tag, e.g how to order +the rooms with a given tag. ```` { @@ -101,16 +128,13 @@ Order is stored using existing [Room Tagging](https://matrix.org/docs/spec/clien } ```` -As defined per `room tagging`ordering information is given under the order key as a number between 0 and 1. The numbers are compared such that 0 is displayed first. Therefore a room with an order of 0.2 would be displayed before a room with an order of 0.7. If a room has a tag without an order key then it should appear after the rooms with that tag that have an order key, fallbacking then to roomID lexical order. +As defined per `room tagging`ordering information is given under the order key as a number between 0 and 1. +The numbers are compared such that 0 is displayed first. Therefore a room with an order of 0.2 would +be displayed before a room with an order of 0.7. If a room has a tag without an order key then it +should appear after the rooms with that tag that have an order key, fallbacking then to roomID lexical order. This alternative has been discarded becaused perceived as confusing in regards of tags intentions. - - -## Potential issues - -## Privacy considerations - ## Unstable prefix The following mapping will be used for identifiers in this MSC during development: From 85d4eca34d047f8835b230088ee2b8e75afe24f4 Mon Sep 17 00:00:00 2001 From: Valere Date: Fri, 11 Jun 2021 11:15:42 +0200 Subject: [PATCH 08/10] Add string to base sample --- proposals/3230-spaces_top_level_order.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/proposals/3230-spaces_top_level_order.md b/proposals/3230-spaces_top_level_order.md index 17a87b661f7..84907ac7744 100644 --- a/proposals/3230-spaces_top_level_order.md +++ b/proposals/3230-spaces_top_level_order.md @@ -44,6 +44,12 @@ In order to find mid points between two orders strings, the `order` string can b a base N number where N is the length of the allowed alphabet. So the string can be converted to a base 10 number for computation and mid point computation, then converted back to base N. +```` +"a" = 65*(95^0) +"z" = 90*(95^0) +"az" = 65*(95^1) + 90*(95^0) +```` + In order to compare strings of different sizes, the shortest string should be padded with \x20 (space) to \x7E (~). From 600185ef81b583c19e99d5721ef76d3ff30cdf35 Mon Sep 17 00:00:00 2001 From: Valere Date: Fri, 11 Jun 2021 11:16:48 +0200 Subject: [PATCH 09/10] Fix copy --- proposals/3230-spaces_top_level_order.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3230-spaces_top_level_order.md b/proposals/3230-spaces_top_level_order.md index 84907ac7744..43b1af72168 100644 --- a/proposals/3230-spaces_top_level_order.md +++ b/proposals/3230-spaces_top_level_order.md @@ -50,7 +50,7 @@ to a base 10 number for computation and mid point computation, then converted ba "az" = 65*(95^1) + 90*(95^0) ```` -In order to compare strings of different sizes, the shortest string should be padded +In order to find mid points between strings of different sizes, the shortest string should be padded with \x20 (space) to \x7E (~). ## Client recommendations: From 7f897e1ea7f6baaef237b7944dbc32fbd6510005 Mon Sep 17 00:00:00 2001 From: Valere Date: Fri, 11 Jun 2021 11:20:48 +0200 Subject: [PATCH 10/10] Fix padding comment --- proposals/3230-spaces_top_level_order.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proposals/3230-spaces_top_level_order.md b/proposals/3230-spaces_top_level_order.md index 43b1af72168..3a982f9b9e9 100644 --- a/proposals/3230-spaces_top_level_order.md +++ b/proposals/3230-spaces_top_level_order.md @@ -51,7 +51,7 @@ to a base 10 number for computation and mid point computation, then converted ba ```` In order to find mid points between strings of different sizes, the shortest string should be padded -with \x20 (space) to \x7E (~). +with the first character of alphabet \x20 (space). ## Client recommendations: @@ -112,7 +112,8 @@ less flexible as a way to define order compared to [0,1]. __Room Tags__ -Order is stored using existing [Room Tagging](https://matrix.org/docs/spec/client_server/latest#room-tagging) mecanism. +Order is stored using existing [Room Tagging](https://matrix.org/docs/spec/client_server/latest#room-tagging) +mechanism. > The tags on a room are received as single m.tag event in the account_data section of a room. The content of the m.tag event is a tags key whose value is an object mapping the name of each tag