Skip to content

Commit 3724024

Browse files
committed
Add criteria for minor and patch releases
1 parent c2e9427 commit 3724024

File tree

1 file changed

+29
-5
lines changed

1 file changed

+29
-5
lines changed

CONTRIBUTING.md

Lines changed: 29 additions & 5 deletions
Original file line numberDiff line numberDiff 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/
3333
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.
3434
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.
3535

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

3838
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).
3939

@@ -153,10 +153,34 @@ The following additional rules should be followed but currently are not enforced
153153

154154
## Release Process and Scope
155155

156-
* Issue #3528: [3.x.y patch release approach](https://github.com/OAI/OpenAPI-Specification/issues/3528)
157-
* 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.
160184

161185
## Branching and Versioning
162186

0 commit comments

Comments
 (0)