Skip to content

Document minimal process necessary for the interim release #1368

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

Closed
wants to merge 5 commits into from
Closed

Document minimal process necessary for the interim release #1368

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
04b07a8
Document minimal process for interim release
jdesrosiers Nov 14, 2022
5a16e2d
PROCESS: Update with feedback from Julian
jdesrosiers Dec 20, 2022
f019cfd
PROCESS: Updates addressing Austin's feedback
jdesrosiers Dec 28, 2022
3cea497
PROCESS: Updates from Karen's feedback
jdesrosiers Jan 5, 2023
7bc8307
PROCESS: Update to remove experimental and deprecated
jdesrosiers Jan 5, 2023
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
PROCESS: Updates addressing Austin's feedback
  • Loading branch information
@jdesrosiers
jdesrosiers committed Dec 28, 2022
commit f019cfd8b83203680b85ec0551e4b78c9816a16e
32 changes: 16 additions & 16 deletions PROCESS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,15 +29,11 @@ to the current URL.
Everything in the specification is considered "stable" by default and subject to
compatibility guarantees. Any changes to stable behaviors in the specification
MUST be backward-compatible with previous versions of the specification and MUST
NOT change in ways that could be problematic for forward-compatibility.
Therefore, it's not necessary for implementations to support previous versions
of the specification separately (excluding "draft" releases).
NOT change in ways that could be problematic for forward compatibility.

_Note: How, when, and how often the specification will be updated are all open
questions that will be decided before any changes are issued following the
initial release. Because releases are compatible, these things shouldn't affect
choices made by implementers or schema authors the same way the "draft" releases
did._
initial release._

### Experimental Behaviors
The specification MAY include sections that introduce experimental behaviors.
Expand All @@ -52,15 +48,19 @@ defined in more detail and is likely to evolve as we learn what works best. Such
evolution will always be compatible with previous versions of this document._

### Compliance
Implementations that express support for a particular release MUST support all
of that release's stable behaviors and SHOULD support any experimental
behaviors. Because releases are compatible, expressing support for a given
release implies support for all previous releases (excluding "draft" releases).
Support for previous releases might have limitations if an implementation
chooses not to support a deprecated behavior.
An implementation is compliant with a given release if it implements all of the
required stable behaviors defined in that release. Experimental behaviors are
Copy link
Member

@karenetheridge karenetheridge Dec 30, 2022

Choose a reason for hiding this comment

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

This sentence implies that stable items are explicitly defined (which is what I think we should do, but not what this document states).
Copy link
Member Author

@jdesrosiers jdesrosiers Jan 4, 2023

Choose a reason for hiding this comment

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

I don't think that sentence implies anything about how stable items are defined, but I'll see if I can make it less ambiguous.

Is it the word "required" that makes you interpret it that way? I included that to make it clear that an optional feature (like the annotation-assertion vocabulary) doesn't need to be implemented even though it's a stable feature.
not required to be considered compliant, but implementing them is highly
encouraged. An implementation that implements behaviors that are not compatible
with the given release is considered compliant only if those behaviors are
disabled by default.

Because releases are compatible, expressing support for a given release implies
support for all previous releases (excluding "draft" releases). Support for
Copy link
Member

@karenetheridge karenetheridge Dec 30, 2022

Choose a reason for hiding this comment

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

But this isn't true right now. It may be true in the future, when we figure out what "backwards compatible" means, but that's premature for this set of changes.
Copy link
Member Author

@jdesrosiers jdesrosiers Jan 4, 2023

Choose a reason for hiding this comment

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

I'll try to make it more clear. This document applies only to releases that were produced using this process.
previous releases might have limitations if an implementation chooses not to
support a deprecated behavior.

### Deprecation
Stable behaviors MAY be marked as "deprecated". Implementations SHOULD support
these behaviors to maintain backward compatibility. Schema authors SHOULD
migrate away from using deprecated behaviors as implementations MAY begin
dropping support for these behaviors at some point.
Stable behaviors MAY be marked as "deprecated". Implementations are expected to
support these behaviors to maintain backward compatibility and schema authors
should migrate away from using these behaviors.
Copy link
Member

@karenetheridge karenetheridge Dec 30, 2022

Choose a reason for hiding this comment

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

Unstable things could also be deprecated - e.g. "we put this in as an experiment, and it didn't work out, so we're going to remove it in the next release".
Copy link
Member Author

@jdesrosiers jdesrosiers Jan 4, 2023

Choose a reason for hiding this comment

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

I hadn't thought about using deprecation that way. Deprecation is one of the things we know needs more discussion. I'll try to reword the current text in a way that doesn't restrict us from deciding to use it that way.