Skip to content

Update the stability policy #834

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Aug 26, 2024
Merged

Update the stability policy #834

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
275813b
Update the stability policy
aphillips Jul 22, 2024
2a38566
A deeper, more thorough rewrite
aphillips Jul 22, 2024
517843d
Update spec/README.md
aphillips Jul 24, 2024
b3d0a08
Update spec/README.md
aphillips Jul 25, 2024
bae17f7
remove well-formed
aphillips Jul 25, 2024
4b40895
Update spec/README.md
aphillips Aug 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 52 additions & 31 deletions spec/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,64 +79,65 @@ 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 make any valid _message_ invalid.

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 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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Updates to this specification will not change the syntactical meaning
Updates to this specification will not change the meaning

(Not sure how "syntactical meaning" is different from just "meaning" here)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Syntactical meaning is: .input is an input declaration.

"Meaning" can be read as "how a specific .input is understood", so .input {$foo @bar=baz} might "change meaning" if we allowed expression attributes and assigned "meaning" to the @bar one. That's why I used the circuitous and painful wording.

Perhaps:

Suggested change
Updates to this specification will not change the syntactical meaning
Updates to this specification will not alter the role assigned to
defined elements of the syntax, except to assign an interpretation to syntax marked as
"reserved for future standardization".

of any syntax defined in this specification except for that syntax marked as
"reserved for future standardization".

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 add any additional Unicode code points to
those in `reserved-annotation-start`.

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.

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.
Updates to this specification will not remove any options or option values
defined in the default registry.

> [!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
Comment on lines +111 to 112
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> Even when this specification or its implementation do not change,
> the functions for date formatting, number formatting and so on
> Even when this specification does not change,
> the implementations of functions for date formatting, number formatting and so on

The functions are part of an implementation, so if the behavior of functions changed, it means that one or more implementations changed.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, although I'm also trying to point out that the function implementation (the code) might also remain static and the output change (because your operating system, for example, got a new copy of CLDR data)

> 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.
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.

> [!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.
Expand All @@ -146,3 +147,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.