From 6f3be3357485aeda0e0224d02d6cdf2b4348498e Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Sun, 8 Apr 2018 22:27:38 -0400 Subject: [PATCH 1/4] Draft features explanation --- DEVELOPMENT.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index b975f55b98..191eb97af2 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -47,6 +47,24 @@ Spec changes should be approved by a majority of the committers. Approval can b No change should be approved until there is documentation for it, supplied in an accompanying PR. +## Draft Features + +Where suitable, features will be introduced as draft but OAI approved extensions. +By introducing new features this way we enable new features to be designed, documented and then implemented by tools that are interested in the feature, without putting the burden of implementation on all tooling. +If the feature is successfully implemented and there is demonstrable value added by the feature, it will become a candidate for inclusion in a future release of the specification, at which point all tools will be expected to support the feature. + +Draft feature extensions are identified by the `x-oas-draft-` prefix and can only be used where existing extensions are permitted. +This ensures no exising tooling will affected by the introduction of the draft feature. +If the feature is deemed appropriate for inclusion in the OAS, the `x-oas-draft-` prefix will be removed. +Tooling that supports draft features should plan for the future removal of the prefix and accomodate the transition period where descriptions exist with and without the prefix. + +Draft features will be documented as Github issues and labeled with the `draft-feature` label. +If during the development of a draft feature, it is determined that the feature needs to change in a way that may break existing draft implementations, the extension name itself may be versioned with a version suffix. e.g. `-v2` + +Not all future new features will be introduced in this way. +Some new features impact the specification in ways that cannot be encapsulated in an extension. +However, where a new feature can be introduced in this way, it should be. + ## Transparency We should always be as transparent as possible. Sometimes there will be discussions that use customer names, sensitive use cases, and so on. These must be anonymized, discussed in a private repository, or conducted offline. From 00be9d5133bf47c43cb1b26604b364f1ef3a9e3d Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Mon, 16 Apr 2018 10:09:58 -0400 Subject: [PATCH 2/4] Updates based on reviews --- DEVELOPMENT.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 191eb97af2..6038bdcc9c 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -54,12 +54,16 @@ By introducing new features this way we enable new features to be designed, docu If the feature is successfully implemented and there is demonstrable value added by the feature, it will become a candidate for inclusion in a future release of the specification, at which point all tools will be expected to support the feature. Draft feature extensions are identified by the `x-oas-draft-` prefix and can only be used where existing extensions are permitted. -This ensures no exising tooling will affected by the introduction of the draft feature. +This ensures no existing tooling will affected by the introduction of the draft feature. If the feature is deemed appropriate for inclusion in the OAS, the `x-oas-draft-` prefix will be removed. -Tooling that supports draft features should plan for the future removal of the prefix and accomodate the transition period where descriptions exist with and without the prefix. +Tooling that supports draft features should plan for the future removal of the prefix. +When tooling adds support for a later version of OAS that includes the final implementation of the feature, it MUST not support the use of the draft prefix for that feature. +Draft features will only be promoted into minor or major releases of the specification and therefore will be transparent to OpenAPI description writers and tooling providers who choose not to use the feature while in its draft state. -Draft features will be documented as Github issues and labeled with the `draft-feature` label. +Draft features will be documented as GitHub issues and labeled with the `draft-feature` label. If during the development of a draft feature, it is determined that the feature needs to change in a way that may break existing draft implementations, the extension name itself may be versioned with a version suffix. e.g. `-v2` +When a draft feature becomes part of a future update to the specification any version suffix will be removed. +Draft features that are deemed not appropriate for inclusion MUST be marked with the `abandoned` label. Not all future new features will be introduced in this way. Some new features impact the specification in ways that cannot be encapsulated in an extension. From c3161bce4eec02575d06a202d947032a1155c19e Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Mon, 30 Apr 2018 11:47:21 -0400 Subject: [PATCH 3/4] Added words for the process of marking a draft-feature ready to be implmented --- DEVELOPMENT.md | 1 + 1 file changed, 1 insertion(+) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 6038bdcc9c..d53d25d3f6 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -64,6 +64,7 @@ Draft features will be documented as GitHub issues and labeled with the `draft-f If during the development of a draft feature, it is determined that the feature needs to change in a way that may break existing draft implementations, the extension name itself may be versioned with a version suffix. e.g. `-v2` When a draft feature becomes part of a future update to the specification any version suffix will be removed. Draft features that are deemed not appropriate for inclusion MUST be marked with the `abandoned` label. +Draft-features that are considered suitably specified for implementation will be marked with the `draft-ready` label. Not all future new features will be introduced in this way. Some new features impact the specification in ways that cannot be encapsulated in an extension. From 26ead2926ce96234ef86ea8f60621744d6555559 Mon Sep 17 00:00:00 2001 From: Darrel Miller Date: Sun, 20 May 2018 15:46:27 -0400 Subject: [PATCH 4/4] Updated new draft-feature statuses --- DEVELOPMENT.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index d53d25d3f6..bcccee5cb9 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -60,11 +60,11 @@ Tooling that supports draft features should plan for the future removal of the p When tooling adds support for a later version of OAS that includes the final implementation of the feature, it MUST not support the use of the draft prefix for that feature. Draft features will only be promoted into minor or major releases of the specification and therefore will be transparent to OpenAPI description writers and tooling providers who choose not to use the feature while in its draft state. -Draft features will be documented as GitHub issues and labeled with the `draft-feature` label. +Draft features will be documented as GitHub issues and labeled with the `draft-feature` label and will be initially labelled as `draft:proposal`. When the proposal is considered sufficiently stable for pilot implementation, it will be labeled `draft:pilot`. If during the development of a draft feature, it is determined that the feature needs to change in a way that may break existing draft implementations, the extension name itself may be versioned with a version suffix. e.g. `-v2` When a draft feature becomes part of a future update to the specification any version suffix will be removed. -Draft features that are deemed not appropriate for inclusion MUST be marked with the `abandoned` label. -Draft-features that are considered suitably specified for implementation will be marked with the `draft-ready` label. +Draft features that are deemed not appropriate for inclusion MUST be marked with the `draft:abandoned` label. +Draft-features that are considered suitably specified and have had successful pilot implementations will be marked with the `draft:graduated` label. Not all future new features will be introduced in this way. Some new features impact the specification in ways that cannot be encapsulated in an extension.