Skip to content

Commit 2ee245c

Browse files
lornajanelornajane
authored
Merge pull request #4154 from handrews/dev-reorg
Describe new spec branch and file layout
2 parents daecd39 + d6de1c0 commit 2ee245c

File tree

2 files changed

+106
-18
lines changed

2 files changed

+106
-18
lines changed

Diff for: ‎CONTRIBUTING.md

+100-13
Original file line numberDiff line numberDiff line change
@@ -14,26 +14,113 @@ 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-
### Current branches and documents open to change
17+
### Changing the schemas
1818

19-
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.
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.
2022

21-
The current (31 July 2024) active releases are:
23+
### Authoritative source of truth
2224

23-
| Version | Branch | File | Notes |
24-
| ------- | ------ | ---- | ----- |
25-
| 3.0.4 | `v3.0.4-dev` | `versions/3.0.4.md` | Soon to be published |
26-
| 3.1.1 | `v3.1.1-dev` | `versions/3.1.1.md` | Soon to be published |
27-
| 3.2.0 | `v3.2.0-dev` | `versions/3.2.0.md` | Planned for late 2024 |
28-
| 4.0.0 | [OAI/sig-moonwalk](https://github.com/OAI/sig-moonwalk) | [discussions only](https://github.com/OAI/sig-moonwalk/discussions) | TBD, some proposals to be backported and published in 3.2.0 |
25+
The [spec site](https://spec.openapis.org) is the source of truth.
2926

30-
### Changing the schemas
27+
This changed in 2024, as the markdown files on `main` do not include certain credits and citations.
28+
29+
## Development and publication process
30+
31+
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+
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+
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+
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).
37+
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+
40+
### Branch diagram (3.1.2, 3.2.0, and later)
41+
42+
Initial steps:
43+
44+
* `dev` branches from `main` at the 3.1.1 release commit
45+
* Each `X.Y-dev` branches from `dev`
46+
47+
Upon release:
48+
49+
* Each `X.Y.Z-rel` branches from the corresponding `X.Y-dev`
50+
* After renaming `src/oas.md`, `X.Y.Z-rel` merges to `main`
51+
* Publishing to the [spec site](https://spec.openapis.org) is triggered by the merge to `main`
52+
53+
Initiating the next minor release after releasing `X.Y.0`:
54+
55+
* The same `X.Y-dev` commit that is the base of `X.Y.0-rel` is merged back to `dev` to keep `src/oas.md` on `dev` in sync with the last minor release
56+
* This `X.Y.0` commit on `dev` is the base of `X.Y+1-dev`
57+
58+
Other notes:
59+
60+
* Patch releases are _not_ merged to `dev`
61+
62+
```mermaid
63+
gitGraph TB:
64+
commit id:"merge 3.1.1.md to main" tag:"3.1.1"
65+
branch dev order:1
66+
commit id:"rename 3.1.1.md to src/oas.md"
67+
branch v3.1-dev order:2
68+
commit id:"update version in src/oas.md to 3.1.2"
69+
checkout dev
70+
branch v3.2-dev order:5
71+
commit id:"update version in src/oas.md to 3.2.0"
72+
commit id:"some 3.2.0 work"
73+
checkout v3.1-dev
74+
commit id:"a 3.1.x fix"
75+
branch v3.1.2-rel order:3
76+
commit id:"rename src/oas.md to versions/3.1.2.md"
77+
checkout main
78+
merge v3.1.2-rel tag:"3.1.2"
79+
checkout v3.2-dev
80+
commit id:"more 3.2.0 work"
81+
checkout v3.1-dev
82+
commit id:"update version in src/oas.md to 3.1.3"
83+
commit id:"another 3.1.x fix"
84+
checkout v3.2-dev
85+
commit id:"still more 3.2.0 work"
86+
merge v3.1-dev id:"merge 3.1.x fixes before releasing"
87+
checkout v3.1-dev
88+
branch v3.1.3-rel order:4
89+
commit id:"rename src/oas.md to versions/3.1.3.md"
90+
checkout v3.2-dev
91+
branch v3.2.0-rel order:6
92+
commit id:"rename src/oas.md to versions/3.2.0.md"
93+
checkout main
94+
merge v3.1.3-rel tag:"3.1.3"
95+
merge v3.2.0-rel tag:"3.2.0"
96+
checkout dev
97+
merge v3.2-dev id:"update dev with minor release"
98+
branch v3.3-dev order:7
99+
checkout v3.1-dev
100+
commit id:"update version in src/oas.md to 3.1.4"
101+
checkout v3.2-dev
102+
commit id:"update version in src/oas.md to 3.2.1"
103+
checkout v3.3-dev
104+
commit id:"update version in src/oas.md to 3.3.0"
105+
```
106+
107+
### Schema development
108+
109+
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).
110+
111+
#### Active branches
112+
113+
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.
31114

32-
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.
115+
The specification under development is `src/oas.md`, which _only_ exists on development branches, not on `main`.
33116

34-
## Authoritative source of truth
117+
The current (20 October 2024) active specification releases are:
35118

36-
* Issue #3576: [What is our authoritative spec URL and how do people find it?](https://github.com/OAI/OpenAPI-Specification/issues/3576)
119+
| Version | Branch | Notes |
120+
| ------- | ------ | ----- |
121+
| 3.1.2 | `v3.1-dev` | active patch release line |
122+
| 3.2.0 | `v3.2-dev` | minor release in development |
123+
| 4.0.0 | [OAI/sig-moonwalk](https://github.com/OAI/sig-moonwalk) | [discussions only](https://github.com/OAI/sig-moonwalk/discussions) |
37124

38125
## Style Guide
39126

Diff for: ‎README.md

+6-5
Original file line numberDiff line numberDiff line change
@@ -37,18 +37,19 @@ Looking to see how you can create your own OpenAPI definition, present it, or ot
3737
## Participation
3838

3939
The current process for developing the OpenAPI Specification is described in
40-
[Development Guidelines](DEVELOPMENT.md).
40+
the [Contributing Guidelines](CONTRIBUTING.md).
41+
4142
Developing the next version of the OpenAPI Specification is guided by the [Technical Steering Committee (TSC)](https://www.openapis.org/participate/how-to-contribute/governance#TDC). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to `main`.
4243

4344
The TSC holds weekly web conferences to review open pull requests and discuss open issues related to the evolving OpenAPI Specification. Participation in weekly calls and scheduled working sessions is open to the community. You can view the entire OpenAPI [technical meeting calendar](https://calendar.google.com/calendar/u/0/[email protected]) online.
4445

4546
The OpenAPI Initiative encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:
4647

47-
* Review the [current specification](versions/3.1.0.md). The human-readable markdown file _is the source of truth_ for the specification.
48-
* Review the [development](DEVELOPMENT.md) process so you understand how the spec is evolving.
49-
* Check the [issues](https://github.com/OAI/OpenAPI-Specification/issues) and [pull requests](https://github.com/OAI/OpenAPI-Specification/pulls) to see if someone has already documented your idea or feedback on the specification. You can follow an existing conversation by subscribing to the existing issue or PR.
48+
* Review the [current specification](https://spec.openapis.org) on the official specification site, which is the source of truth as it includes the full credits and citations.
49+
* Review the [contributing](CONTRIBUTING.md) process so you understand how the spec is evolving.
50+
* Check the [discussions](https://github.com/OAI/OpenAPI-Specification/discussions), [issues](https://github.com/OAI/OpenAPI-Specification/issues) and [pull requests](https://github.com/OAI/OpenAPI-Specification/pulls) to see if someone has already documented your idea or feedback on the specification. You can follow an existing conversation by subscribing to the existing issue or PR.
5051
* Subscribe to an open issue a day (or a week) in your inbox via [CodeTriage.com](https://www.codetriage.com/oai/openapi-specification).
51-
* Create an issue to describe a new concern. If possible, propose a solution.
52+
* Create a discussion to describe a new concern, ideally with clear explanations of related use cases.
5253

5354
Not all feedback can be accommodated, and there may be solid arguments for or against a change being appropriate for the specification.
5455

0 commit comments

Comments
 (0)