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

Draft features explanation #1531

Merged
merged 4 commits into from Jun 11, 2018

Conversation

Projects
None yet
5 participants
@darrelmiller
Member

darrelmiller commented Apr 9, 2018

Update to development guidelines to describe the process of creating draft features.

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 comment has been minimized.

@MikeRalphson

MikeRalphson Apr 9, 2018

Member

"existing"

This comment has been minimized.

@MikeRalphson

MikeRalphson Apr 10, 2018

Member

Is it worth calling out that draft extensions can only be promoted into minor or major (breaking) versions of the spec, not patches? That may be deemed obvious from the rest of the document though.

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.

This comment has been minimized.

@earth2marsh

earth2marsh Apr 9, 2018

Member

GitHub should have a capital H

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`

This comment has been minimized.

@darrelmiller

darrelmiller Apr 9, 2018

Member

Add note about removing suffix when feature becomes included in the spec.

This comment has been minimized.

@darrelmiller

darrelmiller Apr 9, 2018

Member

When a draft feature is deemed not appropriate for inclusion, we should mark the documentation as "obsolete" or "obsoleted by".

@earth2marsh

This comment has been minimized.

Member

earth2marsh commented Apr 9, 2018

Suggest declaring the purpose of this change along the lines of, "This approach provides an official process by which code and spec can coevolve."

@earth2marsh

This comment has been minimized.

Member

earth2marsh commented Apr 12, 2018

In discussion, we talked about the fact that x-oas-draft-… shouldn't be considered in schemas used to validate specs. However, once the feature graduates from draft, should the schema consider draft extensions as invalid OpenAPI?

@usarid also pointed out that overlays may be a way to extend without (or possibly in concert with?) using the spec extension approach.

@handrews

This comment has been minimized.

handrews commented Apr 13, 2018

@earth2marsh I'd say that old x-oas-draft- keywords are still valid, but as with any other x- keyword, support is not reliable. Rather than forbidding them, perhaps implementations SHOULD warn that the feature has graduated?

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.

This comment has been minimized.

@darrelmiller

darrelmiller Apr 30, 2018

Member

Alternative labels: "ready", "ready-to-pilot", "ready-for-trial".
"draft-feature", "draft:abandoned", "draft:approved|ready" Ron & Marsh to duke it out and come to a decision.

This comment has been minimized.

@earth2marsh

earth2marsh May 9, 2018

Member

@webron and I caught up on this and have agreed on:
draft:proposal - we’re still hashing out the details
draft:pilot - go ahead and implement it
draft:graduated - we’ve seen the implementations, it will go into the next minor/major release
draft:abandoned - didn't succeed, do not use

This comment has been minimized.

@darrelmiller

darrelmiller May 14, 2018

Member

Latest status suggestions by @earth2marsh approved by @OAI/tsc

@@ -47,6 +47,29 @@ 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.

This comment has been minimized.

@earth2marsh

earth2marsh May 20, 2018

Member

but here is throwing me off... how about as OAI-approved, draft features?

@earth2marsh

Generally agree with the wording here, but it might be improved with a few small tweaks here and there?

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.

This comment has been minimized.

@earth2marsh

earth2marsh May 20, 2018

Member

SHOULD? :)

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.

This comment has been minimized.

@earth2marsh

earth2marsh May 20, 2018

Member

it will become a candidate seems like it's a candidate for inclusion in a future release even in draft form. Perhaps this is more like, it becomes eligible to be included in a future release?

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 and will be initially labelled as `draft:proposal`. When the proposal is considered sufficiently stable for pilot implementation, it will be labeled `draft:pilot`.

This comment has been minimized.

@earth2marsh

earth2marsh May 20, 2018

Member

Is this saying there will be at least two labels, both a draft-feature and a draft:*? Should it be spelled out that older stage labels are removed?

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 `draft:abandoned` label.
Draft-features that are considered suitably specified and have had successful pilot implementations will be marked with the `draft:graduated` label.

This comment has been minimized.

@earth2marsh

earth2marsh May 20, 2018

Member

Suggest removing - from Draft features to be consistent with prev line.

Draft feature extensions are identified by the `x-oas-draft-` prefix and can only be used where existing extensions are permitted.
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.

This comment has been minimized.

@tedepstein

tedepstein May 21, 2018

Contributor

So the final property name will usually (or always?) be the same as the draft property name, minus the x-oas-draft- prefix, correct? If tool developers can rely on this, at least as the usual/expected case, it makes it somewhat easier to manage the lifecycle.

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.
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.

This comment has been minimized.

@tedepstein

tedepstein May 21, 2018

Contributor

@handrews suggested relaxing this:

I'd say that old x-oas-draft- keywords are still valid, but as with any other x- keyword, support is not reliable. Rather than forbidding them, perhaps implementations SHOULD warn that the feature has graduated?

Was this discussed and rejected for some reason? If not, I think it's a more practical policy, and we should consider adopting it. It will make it easier to migrate OAS documents to new spec versions.

@darrelmiller darrelmiller merged commit 841dc64 into master Jun 11, 2018

2 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details

@darrelmiller darrelmiller deleted the dm/draft-features branch Jun 11, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment