Skip to content

Draft features explanation #1531

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

Merged
merged 4 commits into from
Jun 11, 2018
Merged

Draft features explanation #1531

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6f3be33
Draft features explanation
darrelmiller Apr 9, 2018
00be9d5
Updates based on reviews
darrelmiller Apr 16, 2018
c3161bc
Added words for the process of marking a draft-feature ready to be im…
darrelmiller Apr 30, 2018
26ead29
Updated new draft-feature statuses
darrelmiller May 20, 2018
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
23 changes: 23 additions & 0 deletions DEVELOPMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

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

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

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.
Copy link
Member

Choose a reason for hiding this comment

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

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?


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.
Copy link
Contributor

Choose a reason for hiding this comment

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

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.

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.
Copy link
Contributor

Choose a reason for hiding this comment

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

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

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`.
Copy link
Member

Choose a reason for hiding this comment

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

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.
Copy link
Member

Choose a reason for hiding this comment

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

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


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.
Copy link
Member

Choose a reason for hiding this comment

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

SHOULD? :)


## 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.
Expand Down