You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+29-5Lines changed: 29 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -33,7 +33,7 @@ As of October 2024 (post-OAS 3.0.4 and 3.1.1), the OAS is developed in the `src/
33
33
All work **MUST be done on a fork**, using a branch from the _earliest relevant and [active](#active-branches)_`X.Y-dev` branch, and then submitted as a PR to that `X.Y-dev` branch.
34
34
For example, if a change in November 2024 apples to both 3.1 and 3.2, the PR would go to the `v3.1-dev` branch, which will be merged up to `v3.2-dev` before the next 3.2 release.
35
35
36
-
Releases are published to the [spec site](https://spec.opanapis.org) by creating an `X.Y.Z-rel` branch where `src/oas.md` is renamed to the appropriate `versions/X.Y.Z.md` file and them merged to `main`. The HTML versions of the OAS are automatically generated from the `versions` directory on `main`. This renaming on the `X.Y.Z-rel` branch preserves the commit history for the published file on `main` when using `git log --follow` (as is the case for all older published files).
36
+
Releases are published to the [spec site](https://spec.openapis.org) by creating an `X.Y.Z-rel` branch where `src/oas.md` is renamed to the appropriate `versions/X.Y.Z.md` file and them merged to `main`. The HTML versions of the OAS are automatically generated from the `versions` directory on `main`. This renaming on the `X.Y.Z-rel` branch preserves the commit history for the published file on `main` when using `git log --follow` (as is the case for all older published files).
37
37
38
38
For information on the branch and release strategy for OAS 3.0.4 and 3.1.1 and earlier, see the comments in [issue #3677](https://github.com/OAI/OpenAPI-Specification/issues/3677).
39
39
@@ -153,10 +153,34 @@ The following additional rules should be followed but currently are not enforced
* Issue #3529: [3.x minor release approach](https://github.com/OAI/OpenAPI-Specification/issues/3529)
158
-
* Issue #3715: [Define and document our schema publishing process](https://github.com/OAI/OpenAPI-Specification/issues/3715)
159
-
* Issue #3785: [Style guide / release checklist for the specification](https://github.com/OAI/OpenAPI-Specification/issues/3785)
156
+
This section relates to the 3.x versions only.
157
+
158
+
### Minor Releases
159
+
160
+
Our roadmap for 3.x releases is community-driven, meaning the specification is open for proposed additions by anyone (see [Proposals for Specification Changes](#proposals-for-specification-changes)), in addition to the issues already on the project backlog.
161
+
162
+
Changes in minor releases (such as 3.2, 3.3) meet the following criteria:
163
+
164
+
* Are **backwards-compatible** and be reasonably easy to implement in tooling that already supports the previous minor version.
165
+
For example, new optional fields can be added.
166
+
* Drive quality-of-life improvements to support how OpenAPI is used by practitioners, so that OpenAPI evolves to continue to meet user needs.
167
+
For example, adding fields to support changes in other standards, or adopting common `x-*` extension fields into the specification.
168
+
* Bring the future closer by making changes that are in line with future 3.x releases and the planned OpenAPI 4.x (Moonwalk) specification as the details of that become available.
169
+
* Make the specification document clearer or easier to understand.
170
+
171
+
A minor release is due when there are some meaningful features (including one or a small nummber of headline features).
172
+
173
+
### Patch Releases
174
+
175
+
Patch releases reflect a constant quest for improving the active minor versions of OpenAPI.
176
+
Since we do not edit specification documents after publication, even the smallest change has to be in a new release.
177
+
178
+
Changes in patch releases meet the following criteria:
179
+
180
+
* Minor updates such as spelling or formatting fixes, including link updates.
181
+
* Clarifications or additions that do not change the meaning of the specification.
182
+
183
+
Patch releases are created as often as there are changes to the specification worth releasing.
0 commit comments