From 36b120737cacfadfdcff19bf2afc80f07e59220b Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 8 May 2024 12:19:02 +1200 Subject: [PATCH 1/3] add ADR for extracting unstable features --- adr/2024-05-08-extract-unstable-keywords.md | 56 +++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 adr/2024-05-08-extract-unstable-keywords.md diff --git a/adr/2024-05-08-extract-unstable-keywords.md b/adr/2024-05-08-extract-unstable-keywords.md new file mode 100644 index 00000000..f3e2e012 --- /dev/null +++ b/adr/2024-05-08-extract-unstable-keywords.md @@ -0,0 +1,56 @@ +# Extract Unstable Features for Initial Release + +* Status: accepted +* Deciders: @gregsdennis @jdrosiers @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 still in development. +- `propertyDependencies` - This feature is not technically in the spec and should go through the proposal process. + +## Decision Drivers + +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 + +* We can release a spec earlier that fulfills our users' needs. +* We can continue to develop these features. + +### Negative Consequences + +* These feature will be considered experimental until their proposals are accepted. This may be a hindrance to adoption. + +## Pros and Cons of the Options + +### 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. From 8c0804f1efd20e5e158c0266eedade5f3dd136a3 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Tue, 14 May 2024 09:12:15 +1200 Subject: [PATCH 2/3] Update adr/2024-05-08-extract-unstable-keywords.md Co-authored-by: Jason Desrosiers --- adr/2024-05-08-extract-unstable-keywords.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adr/2024-05-08-extract-unstable-keywords.md b/adr/2024-05-08-extract-unstable-keywords.md index f3e2e012..9a3a0cce 100644 --- a/adr/2024-05-08-extract-unstable-keywords.md +++ b/adr/2024-05-08-extract-unstable-keywords.md @@ -1,7 +1,7 @@ # Extract Unstable Features for Initial Release * Status: accepted -* Deciders: @gregsdennis @jdrosiers @bhutton +* Deciders: @gregsdennis @jdesrosiers @bhutton * Date: 2024-05-08 Technical Story: From 27ff1d6078e36a65158436bb669a39676a509a4c Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Tue, 14 May 2024 10:23:36 +1200 Subject: [PATCH 3/3] update description for output format extraction --- adr/2024-05-08-extract-unstable-keywords.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adr/2024-05-08-extract-unstable-keywords.md b/adr/2024-05-08-extract-unstable-keywords.md index 9a3a0cce..74faf4db 100644 --- a/adr/2024-05-08-extract-unstable-keywords.md +++ b/adr/2024-05-08-extract-unstable-keywords.md @@ -15,7 +15,7 @@ Also the [SDLC proposal](https://github.com/orgs/json-schema-org/discussions/671 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 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