From 275813bf61dacbada6f46d5646533e0681c1dbfa Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 22 Jul 2024 11:13:37 -0700 Subject: [PATCH 1/6] Update the stability policy Based on discussion in the 2024-07-22 call and in PR #829, update the stability policy. --- spec/README.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/spec/README.md b/spec/README.md index a631901c67..9af7add9d4 100644 --- a/spec/README.md +++ b/spec/README.md @@ -79,12 +79,16 @@ A reference to a _term_ looks like this. > The provisions of the stability policy are not in effect until > the conclusion of the technical preview and adoption of this specification. -Updates to this specification will not change -the syntactical meaning, the runtime output, or other behaviour -of valid messages written for earlier versions of this specification -that only use functions defined in this specification. -Updates to this specification will not remove any syntax provided in this version. -Future versions MAY add additional structure or meaning to existing syntax. +Updates to this specification shall not make any well-formed or valid _message_ invalid. +Updates to this specification shall not remove any syntax provided in this version. +Future versions might add additional structure or meaning to existing syntax. + +Updates to this specification shall not change the syntactical meaning +of any syntax defined in this specification except for that syntax marked as +"reserved for future standardization". + +Updates to this specification shall not assign any meaning or change the syntactical +requirements for any private-use annotation. Updates to this specification will not remove any reserved keywords or sigils. @@ -95,9 +99,11 @@ Updates to this specification will not reserve or assign meaning to any character "sigils" except for those in the `reserved` production. Updates to this specification -will not remove any functions defined in the default registry nor -will they remove any options or option values. -Additional options or option values MAY be defined. +will not remove any functions defined in the default registry. + +Updates to this specification will not remove any options or option values +defined in the default registry. +Additional options or additional option values for existing options MAY be defined. > [!NOTE] > This does not guarantee that the results of formatting will never change. From 2a38566d72900f3cbf73871b389161b1ab6aafa9 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 22 Jul 2024 16:21:42 -0700 Subject: [PATCH 2/6] A deeper, more thorough rewrite - Standardizes the phrasing completely. - Moves all potential future changes (which are not, after all, stability policies) to an "important" block - Removes duplication - Separates functions, options, and option values into separate guarantees - Clarifies the note about formatting changing over time --- spec/README.md | 67 ++++++++++++++++++++++++++++---------------------- 1 file changed, 37 insertions(+), 30 deletions(-) diff --git a/spec/README.md b/spec/README.md index 9af7add9d4..b0e0917f31 100644 --- a/spec/README.md +++ b/spec/README.md @@ -79,45 +79,39 @@ A reference to a _term_ looks like this. > The provisions of the stability policy are not in effect until > the conclusion of the technical preview and adoption of this specification. -Updates to this specification shall not make any well-formed or valid _message_ invalid. -Updates to this specification shall not remove any syntax provided in this version. -Future versions might add additional structure or meaning to existing syntax. +Updates to this specification will not make any well-formed or valid _message_ invalid. -Updates to this specification shall not change the syntactical meaning +Updates to this specification will not remove any syntax provided in this version. + +Updates to this specification will not change the syntactical meaning of any syntax defined in this specification except for that syntax marked as "reserved for future standardization". -Updates to this specification shall not assign any meaning or change the syntactical +Updates to this specification will not assign any meaning to or change the syntactical requirements for any private-use annotation. Updates to this specification will not remove any reserved keywords or sigils. -> [!NOTE] -> Future versions may define new keywords. - -Updates to this specification will not reserve or assign meaning to -any character "sigils" except for those in the `reserved` production. +Updates to this specification will not add any additional Unicode code points to +those in `reserved-annotation-start`. -Updates to this specification -will not remove any functions defined in the default registry. +Updates to this specification will not remove any functions defined in the default registry. Updates to this specification will not remove any options or option values defined in the default registry. -Additional options or additional option values for existing options MAY be defined. > [!NOTE] -> This does not guarantee that the results of formatting will never change. -> Even when the specification doesn't change, +> The foregoing policies are _not_ a guarantee that the results of formatting will never change. +> Even when this specification or its implementation do not change, > the functions for date formatting, number formatting and so on -> will change their results over time. - -Later specification versions MAY make previously invalid messages valid. +> can change their results over time or behave differently due to local runtime +> differences in implementation or changes to locale data +> (such as due to the release of new CLDR versions). Updates to this specification will not introduce message syntax that, when parsed according to earlier versions of this specification, would produce syntax or data model errors. -Such messages MAY produce errors when formatted -according to an earlier version of this specification. +Such messages can produce errors when formatted according to an earlier version of this specification. From version 2.0, MessageFormat will only reserve, define, or require function names or function option names @@ -127,22 +121,15 @@ All other names in these categories are reserved for the use of implementations > [!NOTE] > Users defining custom names SHOULD include at least one character outside these ranges > to ensure that they will be compatible with future versions of this specification. +> They SHOULD also use the namespace feature to avoid collisions with other implementations. -Later versions of this specification will not introduce changes +Future versions of this specification will not introduce changes to the data model that would result in a data model representation based on this version being invalid. > For example, existing interfaces or fields will not be removed. -Later versions of this specification MAY introduce changes -to the data model that would result in future data model representations -not being valid for implementations of this version of the data model. - -> For example, a future version could introduce a new keyword, -> whose data model representation would be a new interface -> that is not recognized by this version's data model. - -Later specification versions will not introduce syntax that cannot be +Future versions of this specification will not introduce syntax that cannot be represented by this version of the data model. > For example, a future version could introduce a new keyword. @@ -152,3 +139,23 @@ represented by this version of the data model. > Both data models would be "valid" in their context, > but this version's would be missing any functionality for the new statement type. +> [!IMPORTANT] +> This stability policy allows any of the following, non-exhaustive list, of changes +> in future versions of this specification: +> - Future versions may add additional structure or meaning to existing syntax. +> - Future versions may define new keywords. +> - Future versions may define annotations that use portions of the `reserved-annotation` +> syntax. +> - Future versions may make previously invalid messages valid. +> - Future versions may define additional functions in the default registry +> or may reserve the names of functions for the purposes of interoperability. +> - Future versions may define additional options to existing functions. +> - Future versions may define additional option values for existing options. +> - Future versions may deprecate functions, options, or option values. +> - Future versions of this specification may introduce changes +> to the data model that would result in future data model representations +> not being valid for implementations of this version of the data model. +> - For example, a future version could introduce a new keyword, +> whose data model representation would be a new interface +> that is not recognized by this version's data model. + From 517843ddfd95304a66265015a27570a440da26cf Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 24 Jul 2024 15:12:53 -0700 Subject: [PATCH 3/6] Update spec/README.md Co-authored-by: Tim Chevalier --- spec/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec/README.md b/spec/README.md index b0e0917f31..221ba870a4 100644 --- a/spec/README.md +++ b/spec/README.md @@ -111,7 +111,9 @@ defined in the default registry. Updates to this specification will not introduce message syntax that, when parsed according to earlier versions of this specification, would produce syntax or data model errors. -Such messages can produce errors when formatted according to an earlier version of this specification. +Messages that use syntax introduced in a future version of this specification +could produce resolution or message function errors +when formatted according to an earlier version of this specification. From version 2.0, MessageFormat will only reserve, define, or require function names or function option names From b3d0a086565b3143a74b9904ada1c1c469ecf0c1 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Thu, 25 Jul 2024 06:45:40 -0700 Subject: [PATCH 4/6] Update spec/README.md Co-authored-by: Eemeli Aro --- spec/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/README.md b/spec/README.md index 221ba870a4..99a1a63e85 100644 --- a/spec/README.md +++ b/spec/README.md @@ -115,7 +115,7 @@ Messages that use syntax introduced in a future version of this specification could produce resolution or message function errors when formatted according to an earlier version of this specification. -From version 2.0, MessageFormat will only reserve, define, or require +Updates to this specification will only reserve, define, or require function names or function option names consisting of characters in the ranges a-z, A-Z, and 0-9. All other names in these categories are reserved for the use of implementations or users. From bae17f7a277858447e297598db4f7023f96d417f Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Thu, 25 Jul 2024 09:27:29 -0700 Subject: [PATCH 5/6] remove well-formed --- spec/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/README.md b/spec/README.md index 99a1a63e85..d89827a7e7 100644 --- a/spec/README.md +++ b/spec/README.md @@ -79,7 +79,7 @@ A reference to a _term_ looks like this. > The provisions of the stability policy are not in effect until > the conclusion of the technical preview and adoption of this specification. -Updates to this specification will not make any well-formed or valid _message_ invalid. +Updates to this specification will not make any valid _message_ invalid. Updates to this specification will not remove any syntax provided in this version. From 4b4089572acad3ffb10aeb56934978a3fa06a1a8 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Thu, 22 Aug 2024 13:09:47 -0700 Subject: [PATCH 6/6] Update spec/README.md --- spec/README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/spec/README.md b/spec/README.md index d89827a7e7..b85cfa56f3 100644 --- a/spec/README.md +++ b/spec/README.md @@ -83,6 +83,12 @@ Updates to this specification will not make any valid _message_ invalid. Updates to this specification will not remove any syntax provided in this version. +Updates to this specification MUST NOT specify an error for any message +that previously did not specify an error. + +Updates to this specification MUST NOT specify the use of a fallback value for any message +that previously did not specify a fallback value. + Updates to this specification will not change the syntactical meaning of any syntax defined in this specification except for that syntax marked as "reserved for future standardization".