Skip to content

Commit 6f3be33

Browse files
committed
Draft features explanation
1 parent 2dd0d79 commit 6f3be33

File tree

1 file changed

+18
-0
lines changed

1 file changed

+18
-0
lines changed

DEVELOPMENT.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,24 @@ Spec changes should be approved by a majority of the committers. Approval can b
4747

4848
No change should be approved until there is documentation for it, supplied in an accompanying PR.
4949

50+
## Draft Features
51+
52+
Where suitable, features will be introduced as draft but OAI approved extensions.
53+
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.
54+
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.
55+
56+
Draft feature extensions are identified by the `x-oas-draft-` prefix and can only be used where existing extensions are permitted.
57+
This ensures no exising tooling will affected by the introduction of the draft feature.
58+
If the feature is deemed appropriate for inclusion in the OAS, the `x-oas-draft-` prefix will be removed.
59+
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.
60+
61+
Draft features will be documented as Github issues and labeled with the `draft-feature` label.
62+
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`
63+
64+
Not all future new features will be introduced in this way.
65+
Some new features impact the specification in ways that cannot be encapsulated in an extension.
66+
However, where a new feature can be introduced in this way, it should be.
67+
5068
## Transparency
5169

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

0 commit comments

Comments
 (0)