Skip to content

Add data model to stability policy #643

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
Feb 15, 2024
Merged

Add data model to stability policy #643

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ad20824
Add data model to stability policy
aphillips Feb 13, 2024
1d08031
Apply suggestions from @macchiati
aphillips Feb 13, 2024
25047b2
Update README.md
aphillips Feb 13, 2024
20b1587
Update spec/README.md
aphillips Feb 14, 2024
1dd6f37
Update spec/README.md
aphillips Feb 14, 2024
3083d59
Update spec/README.md
aphillips Feb 14, 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
25 changes: 25 additions & 0 deletions spec/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,3 +123,28 @@ 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.

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

@stasm stasm Feb 15, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

What about changes to the existing fields and interfaces?

IIUC, this parts says that if we ever un-reserve, say, the % sigil, we will also need to keep it on the list of sigils inside UnsupportedAnnotation:

interface UnsupportedAnnotation {
  type: "unsupported-annotation";
  sigil: "!" | "%" | "^" | "&" | "*" | "+" | "<" | ">" | "?" | "~";
  source: string;
}

Otherwise, (i.e. if we remove % from the list), data model representations produced by older implementations will not be valid.

What was the reason for including the sigil field in UnsupportedAnnotation? Could we move the sigil into the source?

Copy link
Collaborator

@eemeli eemeli Feb 15, 2024

Choose a reason for hiding this comment

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

Good point. Including it in the source string would be a better choice for future compatibility.


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
represented by this version of the data model.

> For example, a future version could introduce a new keyword.
> The future version's data model would provide an interface for that keyword
> while this version of the data model would parse the value into
> the interface `UnsupportedStatement`.
> Both data models would be "valid" in their context,
> but this version's would be missing any functionality for the new statement type.