|
2 | 2 |
|
3 | 3 | This document intends to establish guidelines which build a transparent, open mechanism for deciding how to evolve the OpenAPI Specification. The OpenAPI Technical Steering Committee (TSC) will initially follow these processes when merging changes from external contributors or from the TSC itself. This guideline document will be adjusted as practicality dictates.
|
4 | 4 |
|
| 5 | +### Essential Policies |
| 6 | + |
| 7 | +If in doubt about a policy, please [ask on our Slack](https://communityinviter.com/apps/open-api/openapi) before opening a PR. |
| 8 | + |
| 9 | +_Note that the later sections of this document have not been updated recently. Until that has happened, if this section and later sections disagree, this section is to be considered the current policy._ |
| 10 | + |
| 11 | +#### No changes to published specifications |
| 12 | + |
| 13 | +No changes, ***no matter how trivial***, are ever made to the contents of published specifications. The only potential changes to those documents are updates to link URLs _if and only if_ the targeted document is moved by a 3rd party. Other changes to link URLs are not allowed. |
| 14 | + |
| 15 | +#### Current branches and documents open to change |
| 16 | + |
| 17 | +The first PR for a change should be against the oldest release line to which it applies. Changes can then be forward-ported as appropriate. |
| 18 | + |
| 19 | +The current (February 2024) active releases are: |
| 20 | + |
| 21 | +| Version | Branch | File | |
| 22 | +| ------- | ------ | ---- | |
| 23 | +| 3.0.4 | `v3.0.4-dev` | `versions/3.0.4.md` | |
| 24 | +| 3.1.1 | `v3.1.1-dev` | `versions/3.1.1.md` | |
| 25 | +| 3.2.0 | `v3.2.0-dev` | `versions/3.2.0.md` | |
| 26 | +| 4.0.0 | [OAI/sig-moonwalk](https://github.com/OAI/sig-moonwalk) | [discussions only](https://github.com/OAI/sig-moonwalk/discussions) | |
| 27 | + |
| 28 | +#### Changing the schemas |
| 29 | + |
| 30 | +Schemas are only changed _after_ the specification is changed. Changes are made on the `main` branch, and should be made to the YAML version _only_. The JSON version will be generated automatically. |
| 31 | + |
5 | 32 | ## OAI Specification Driving factors
|
6 | 33 |
|
7 | 34 | The OpenAPI Specification should be use-case driven. We can specify support for hypothetical use cases as we see fit, but specifications should be backed by realistic scenarios.
|
|
0 commit comments