Skip to content

Commit 7adb0eb

Browse files
committed
Update schema development process
And also add some section headers and clarify publishing a bit.
1 parent a0848b9 commit 7adb0eb

File tree

1 file changed

+11
-11
lines changed

1 file changed

+11
-11
lines changed

CONTRIBUTING.md

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,6 @@ If in doubt about a policy, please [ask on our Slack](https://communityinviter.c
1414

1515
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.
1616

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-
2317
### Authoritative source of truth
2418

2519
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
3024

3125
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.
3226

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+
3331
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.
3432
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.
3533

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
3741

3842
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).
3943

@@ -156,10 +160,6 @@ gitGraph TB:
156160
commit id:"3.3 work"
157161
```
158162

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-
163163
#### Active branches
164164

165165
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

Comments
 (0)