From fac5d60bc63880944dd4994718a886f956c3f088 Mon Sep 17 00:00:00 2001 From: Peter Thatcher Date: Tue, 3 Sep 2019 13:27:34 -0700 Subject: [PATCH 1/4] Add section about type key backwards compatibility. --- index.bs | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/index.bs b/index.bs index 7c86130..a536c66 100644 --- a/index.bs +++ b/index.bs @@ -1687,6 +1687,31 @@ Open Screen Protocol messages. An agent should not send extension fields to another agent unless that agent advertises an extension capability ID in its [=agent-info=] that indicates that it understands the extension fields. +Type Key Backwards Compatibility +-------------------------------- + +As messages are modified or extended over time, certain rules must be followed +to maintain backwards compatibiilty with agents that understand older versions +of messages. + +1. If a required field is added to or removed from a message, a new type key must +be assigned to the message. Is is effectively a new message and must not be sent +unless the receiving agent is known to understand the new type key. + +1. If an optional field is added to a message, the type key may remain unchanged +if the behavior of an older client that does not understand the added field is +compatible with newer clients that do understand the added field. Otherwise, +a new type key must be assigned. + +1. If an optional field is removed from a message, the type key may remain unchanged +if the behavior of a newer client that does not understand the remove field is +compatible with older clients that do understand the removed field. Otherwise, +a new type key must be assigned. Messages that use array-based grouping +(such as audio-frame) are very unlikely to remain compatible when removing +fields from an array-based grouping, so a new type key should be assigned when +removing fields from an array-based grouping. + + Security and Privacy {#security-privacy} ==================== From 7ffcfd3dd99a08e91b03742f57ac539d0a7e3b25 Mon Sep 17 00:00:00 2001 From: Peter Thatcher Date: Wed, 4 Sep 2019 12:56:48 -0700 Subject: [PATCH 2/4] Improve the type key backwards compatibilty --- index.bs | 51 ++++++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/index.bs b/index.bs index a536c66..d60f5ef 100644 --- a/index.bs +++ b/index.bs @@ -500,6 +500,32 @@ request they are associated with. Issue(139): Clarify scoping/uniqueness of request IDs. +Type Key Backwards Compatibility +-------------------------------- + +As messages are modified or extended over time, certain rules must be followed +to maintain backwards compatibiilty with agents that understand older versions +of messages. + +1. If a required field is added to or removed from a message, a new type key must +be assigned to the message. Is is effectively a new message and must not be sent +unless the receiving agent is known to understand the new type key. + +1. If an optional field is added to a message, the type key may remain unchanged +if the behavior of older receiving agents that do not understand the added field is +compatible with newer sendering agents that do understand the added field. Otherwise, +a new type key must be assigned. + +1. If an optional field is removed from a message, the type key may remain unchanged +if the behavior of newer receiving agents that do not understand the removed field is +compatible with older sending agents that do understand the removed field. Otherwise, +a new type key must be assigned. + +1. Required fields may not be added or removed from array-based messages, such +as audio-frame. + + + Authentication {#authentication} ================================ @@ -1687,31 +1713,6 @@ Open Screen Protocol messages. An agent should not send extension fields to another agent unless that agent advertises an extension capability ID in its [=agent-info=] that indicates that it understands the extension fields. -Type Key Backwards Compatibility --------------------------------- - -As messages are modified or extended over time, certain rules must be followed -to maintain backwards compatibiilty with agents that understand older versions -of messages. - -1. If a required field is added to or removed from a message, a new type key must -be assigned to the message. Is is effectively a new message and must not be sent -unless the receiving agent is known to understand the new type key. - -1. If an optional field is added to a message, the type key may remain unchanged -if the behavior of an older client that does not understand the added field is -compatible with newer clients that do understand the added field. Otherwise, -a new type key must be assigned. - -1. If an optional field is removed from a message, the type key may remain unchanged -if the behavior of a newer client that does not understand the remove field is -compatible with older clients that do understand the removed field. Otherwise, -a new type key must be assigned. Messages that use array-based grouping -(such as audio-frame) are very unlikely to remain compatible when removing -fields from an array-based grouping, so a new type key should be assigned when -removing fields from an array-based grouping. - - Security and Privacy {#security-privacy} ==================== From e4ea784370f7701c1b81d40042ad95aee039375f Mon Sep 17 00:00:00 2001 From: Peter Thatcher Date: Wed, 4 Sep 2019 13:01:12 -0700 Subject: [PATCH 3/4] Make indirect add/remove expliclity included in backwards compat rules --- index.bs | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/index.bs b/index.bs index d60f5ef..d8bdfa1 100644 --- a/index.bs +++ b/index.bs @@ -507,21 +507,26 @@ As messages are modified or extended over time, certain rules must be followed to maintain backwards compatibiilty with agents that understand older versions of messages. -1. If a required field is added to or removed from a message, a new type key must -be assigned to the message. Is is effectively a new message and must not be sent -unless the receiving agent is known to understand the new type key. - -1. If an optional field is added to a message, the type key may remain unchanged -if the behavior of older receiving agents that do not understand the added field is -compatible with newer sendering agents that do understand the added field. Otherwise, -a new type key must be assigned. - -1. If an optional field is removed from a message, the type key may remain unchanged -if the behavior of newer receiving agents that do not understand the removed field is -compatible with older sending agents that do understand the removed field. Otherwise, -a new type key must be assigned. - -1. Required fields may not be added or removed from array-based messages, such +1. If a required field is added to or removed from a message (either to/from the +message directly or indirectly through the field of a field), a new type key +must be assigned to the message. Is is effectively a new message and must not +be sent unless the receiving agent is known to understand the new type key. + +1. If an optional field is added to a message (either to the message directly +or indirectly through the field of a field), the type key may remain unchanged +if the behavior of older receiving agents that do not understand the added field +is compatible with newer sendering agents that do understand the added field. +Otherwise, a new type key must be assigned. + + +1. If an optional field is removed from a message (either from the message +directly or indirectly through the field of a field), the type key may remain +unchanged if the behavior of newer receiving agents that do not understand the +removed field is compatible with older sending agents that do understand the +removed field. Otherwise, a new type key must be assigned. + +1. Required fields may not be added or removed from array-based messages (either +to/from the message directly or indirectly through the field of a field), such as audio-frame. From dae3178a521074222d4e96313e4fc1629373ed9a Mon Sep 17 00:00:00 2001 From: Peter Thatcher Date: Thu, 5 Sep 2019 17:21:59 -0700 Subject: [PATCH 4/4] Fix some text during review --- index.bs | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/index.bs b/index.bs index d8bdfa1..a613534 100644 --- a/index.bs +++ b/index.bs @@ -515,18 +515,16 @@ be sent unless the receiving agent is known to understand the new type key. 1. If an optional field is added to a message (either to the message directly or indirectly through the field of a field), the type key may remain unchanged if the behavior of older receiving agents that do not understand the added field -is compatible with newer sendering agents that do understand the added field. +is compatible with newer sending agents that include the field. Otherwise, a new type key must be assigned. - 1. If an optional field is removed from a message (either from the message directly or indirectly through the field of a field), the type key may remain unchanged if the behavior of newer receiving agents that do not understand the -removed field is compatible with older sending agents that do understand the -removed field. Otherwise, a new type key must be assigned. +removed field is compatible with older sending agents that include the field. +Otherwise, a new type key must be assigned. -1. Required fields may not be added or removed from array-based messages (either -to/from the message directly or indirectly through the field of a field), such +1. Required fields may not be added or removed from array-based messages, such as audio-frame.