Skip to content

Add ADR for extracting unstable features #1505

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.

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 3 commits into from
May 22, 2024
Merged
Changes from all commits
Commits
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
56 changes: 56 additions & 0 deletions adr/2024-05-08-extract-unstable-keywords.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Extract Unstable Features for Initial Release

* Status: accepted
* Deciders: @gregsdennis @jdesrosiers @bhutton
* Date: 2024-05-08

Technical Story:

@gregsdennis [proposed](https://github.com/json-schema-org/json-schema-spec/issues/1443#issuecomment-2099427543) that an ADR be created to document that unstable features be extracted before the stable release.

Also the [SDLC proposal](https://github.com/orgs/json-schema-org/discussions/671) which lists features that need to be put into the proposal process.

## Context and Problem Statement

In creating a stable spec release, it's important that all included features are well-developed and their behaviors are finalized. As such, the following features will be extracted before the stable release.

- `$vocabulary` - This feature is still in development.
- Output formats - This feature is being extracted to its own spec anyway. (See [PR](https://github.com/json-schema-org/json-schema-spec/pull/1429) for more info and link to discussion.)
- `propertyDependencies` - This feature is not technically in the spec and should go through the proposal process.

## Decision Drivers <!-- optional -->

We can't publish a stable spec that contains unstable features. Thus we need to remove them.

## Considered Options

1. Extract unfinished features and put them through the proposal process.
2. Complete the features before releasing the spec.

## Decision Outcome

Chosen option: Extract unfinished features and put them through the proposal process.

This allows us to release a stable version of the specification while continuing to develop these features.

### Positive Consequences <!-- optional -->

* We can release a spec earlier that fulfills our users' needs.
* We can continue to develop these features.

### Negative Consequences <!-- optional -->

* These feature will be considered experimental until their proposals are accepted. This may be a hindrance to adoption.

## Pros and Cons of the Options <!-- optional -->

### Extract unfinished features and put them through the proposal process

* Good, because we can release a spec earlier that fulfills our users' needs.
* Good, because we can continue to develop these features.
* Bad, because these features are experimental now.

### Complete the features before releasing the spec

* Good, because the features will be ready to use when the spec releases.
* Bad, because the spec may not release if we can't finalize the features.
Loading