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
+11-11Lines changed: 11 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,12 +14,6 @@ If in doubt about a policy, please [ask on our Slack](https://communityinviter.c
14
14
15
15
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.
16
16
17
-
### Changing the schemas
18
-
19
-
Schemas are only changed _after_ the specification is changed.
20
-
Changes are made to the YAML versions on the `main` branch.
21
-
The JSON versions are generated when published to the [spec site](https://spec.openapis.org/), at which time the `WORK-IN-PROGRESS` URI placeholders are replaced with the publication date.
22
-
23
17
### Authoritative source of truth
24
18
25
19
The [spec site](https://spec.openapis.org) is the source of truth.
@@ -30,10 +24,20 @@ This changed in 2024, as the markdown files on `main` do not include certain cre
30
24
31
25
As of October 2024 (post-OAS 3.0.4 and 3.1.1), the OAS is developed in the `src/oas.md` file on minor release `X.Y-dev` branches that are derived from the baseline `dev` branch.
32
26
27
+
Schema changes are made on the same branch, but can be released independently. When making a specification change for a new minor or major release that has a schema impact, including the schema change in the PR is preferred. Patch releases cannot contain changes that _require_ a schema update.
28
+
29
+
### Using forks
30
+
33
31
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
32
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
33
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).
34
+
### Publishing
35
+
36
+
The specification and schemas 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).
37
+
38
+
The publishing process for schemas is still under discussion (see issues [#3715](https://github.com/OAI/OpenAPI-Specification/issues/3715) and [#3716](https://github.com/OAI/OpenAPI-Specification/issues/3716)), with the current proposal being to release them directly from the `X.Y-dev` branch without merging to `main`, as the schemas in source control have placeholder identifiers and are not intended to be used as-is.
39
+
40
+
### Historical branch strategy
37
41
38
42
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
43
@@ -156,10 +160,6 @@ gitGraph TB:
156
160
commit id:"3.3 work"
157
161
```
158
162
159
-
### Schema development
160
-
161
-
Development of schemas [currently occurs on `main`](#changing-the-schemas), but the process is [being re-evaluated and is likely to change](https://github.com/OAI/OpenAPI-Specification/issues/3715).
162
-
163
163
#### Active branches
164
164
165
165
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.
0 commit comments