Skip to content

Linkify stability policy #941

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 2 commits into from
Nov 18, 2024
Merged

Linkify stability policy #941

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
de6ec3e
Linkify stability policy
aphillips Nov 16, 2024
d27dd84
Fix normativity of examples and notes
aphillips Nov 17, 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
50 changes: 27 additions & 23 deletions spec/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,12 @@ A **_term_** looks like this when it is defined in this specification.

A reference to a _term_ looks like this.

> [!NOTE]
> Examples are non-normative and styled like this.

> [!IMPORTANT]
> Text marked "Important" like this are normative.

### Stability Policy

> [!IMPORTANT]
Expand All @@ -84,42 +88,42 @@ 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 will not specify an error for any message
that previously did not specify an error.
Updates to this specification will not specify an _error_ for any _message_
that previously did not specify an _error_.

Updates to this specification will 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 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.

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

Updates to this specification will not remove any options or option values
defined in the default registry.
Updates to this specification will not remove any _options_ or _option_ values
defined in the default function registry.

Copy link
Member

@macchiati macchiati Nov 16, 2024

Choose a reason for hiding this comment

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

One additional item. We should add the following clause for clarity.

Suggested change
Updates to this specification may **deprecate** _functions_, _options_, and _operands_ defined in the default registry, as is standard practice in Unicode specifications. This is to indicate that the use of those _functions_, _options_, or _operands_ is discouraged. However, they are never removed, and implementations can continue to support them.

Copy link
Member Author

@aphillips aphillips Nov 17, 2024

Choose a reason for hiding this comment

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

We already say this (line 146), except we don't mention operands in the stability policy and, of course, it's much less explanatory. Note that the stability policy is about what we won't do.

Making this change would be normative and require WG consensus, so I'll change the tags and remove fast-track until we discuss Monday.

Copy link
Member

@macchiati macchiati Nov 17, 2024

Choose a reason for hiding this comment

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

Sounds good

Copy link
Collaborator

@eemeli eemeli Nov 17, 2024

Choose a reason for hiding this comment

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

Eh, this is a completely separate change from this PR. It really should be handled separately, but we're going to feature-creep it into this same change once again, yes?

Something like this was previously discussed here: #883 (comment), and the spec text already includes this, which is in an [!IMPORTANT] block and therefore normative:

message-format-wg/spec/README.md

Line 142 in f3344b5

> - Future versions may deprecate (but not remove) keywords, functions, options, or option values.

Copy link
Member Author

@aphillips aphillips Nov 17, 2024

Choose a reason for hiding this comment

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

Eh, this is a completely separate change from this PR. It really should be handled separately, but we're going to feature-creep it into this same change once again, yes?

Under normal circumstances, I would insist on it. But I'm hoping to be done tomorrow.

> [!NOTE]
> 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
> the _function handlers_ for date formatting, number formatting and so on
> 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 only reserve, define, or require
function identifiers and function option identifiers
_function_ _identifiers_ and _function_ _option_ _identifiers_
which satisfy either of the following two requirements:
- Includes no namespace,
and has a name consisting of characters in the ranges a-z, A-Z, and 0-9,
- Includes no _namespace_,
and has a _name_ consisting of characters in the ranges a-z, A-Z, and 0-9,
and the characters U+002E FULL STOP `.`, U+002D HYPHEN-MINUS `-`, and U+005F LOW LINE `_`.
- Uses a namespace consisting of a single character in the ranges a-z and A-Z.
- Uses a _namespace_ consisting of a single character in the ranges a-z and A-Z.

All other identifiers in these categories are reserved for the use of implementations or users.
All other _identifiers_ in these categories are reserved for the use of implementations or users.

> [!NOTE]
> Users defining custom identifiers SHOULD include at least one character outside these ranges
> Users defining custom _identifiers_ 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.
> They SHOULD also use the _namespace_ feature to avoid collisions with other implementations.

Future versions of this specification will not introduce changes
to the data model that would result in a data model representation
Expand All @@ -133,17 +137,17 @@ based on this version being invalid.
> - Future versions may define new syntax and structures
> that would not be supported by this version of the specification.
> - Future versions may add additional structure or meaning to existing syntax.
> - Future versions may define new keywords.
> - 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 (but not remove) keywords, functions, options, or option values.
> - Future versions may define new _keywords_.
> - 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 (but not remove) _keywords_, _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,
> - 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.