Skip to content

Commit 281b6e9

Browse files
handrewshandrews
committed
Describe new spec branch and file layout
With related process tweaking.
1 parent e9dc186 commit 281b6e9

File tree

2 files changed

+88
-20
lines changed

2 files changed

+88
-20
lines changed

‎CONTRIBUTING.md

+82-15
Original file line numberDiff line numberDiff line change
@@ -14,26 +14,93 @@ 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
18-
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.
20-
21-
The current (31 July 2024) active releases are:
17+
### Changing the schemas
2218

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 |
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 publised to the spec site, at which time the `WORK-IN-PROGRESS` URI placeholders are replaced with the publication date.
22+
23+
### Authoritative source of truth
24+
25+
The [spec site](https://spec.openapis.org) is the source of truth.
26+
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+
```mermaid
43+
gitGraph TB:
44+
commit id:"merge 3.1.1.md to main" tag:"3.1.1"
45+
branch dev order:1
46+
commit id:"rename 3.1.1.md to src/oas.md"
47+
branch v3.1-dev order:2
48+
commit id:"update version in src/oas.md to 3.1.2"
49+
checkout dev
50+
branch v3.2-dev order:5
51+
commit id:"update version in src/oas.md to 3.2.0"
52+
commit id:"some 3.2.0 work"
53+
checkout v3.1-dev
54+
commit id:"a 3.1.x fix"
55+
branch v3.1.2-rel order:3
56+
commit id:"rename src/oas.md to versions/3.1.2.md"
57+
checkout main
58+
merge v3.1.2-rel tag:"3.1.2"
59+
checkout v3.2-dev
60+
commit id:"more 3.2.0 work"
61+
checkout v3.1-dev
62+
commit id:"update version in src/oas.md to 3.1.3"
63+
commit id:"another 3.1.x fix"
64+
checkout v3.2-dev
65+
commit id:"still more 3.2.0 work"
66+
merge v3.1-dev id:"merge 3.1.x fixes before releasing"
67+
checkout v3.1-dev
68+
branch v3.1.3-rel order:4
69+
commit id:"rename src/oas.md to versions/3.1.3.md"
70+
checkout v3.2-dev
71+
branch v3.2.0-rel order:6
72+
commit id:"rename src/oas.md to versions/3.2.0.md"
73+
checkout main
74+
merge v3.1.3-rel tag:"3.1.3"
75+
merge v3.2.0-rel tag:"3.2.0"
76+
checkout dev
77+
merge v3.2-dev id:"update dev with minor release"
78+
branch v3.3-dev order:7
79+
checkout v3.1-dev
80+
commit id:"update version in src/oas.md to 3.1.4"
81+
checkout v3.2-dev
82+
commit id:"update version in src/oas.md to 3.2.1"
83+
checkout v3.3-dev
84+
commit id:"update version in src/oas.md to 3.3.0"
85+
```
86+
87+
### Schema development
88+
89+
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).
90+
91+
#### Active branches
2992

30-
### Changing the schemas
93+
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.
3194

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

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

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

38105
## Style Guide
39106

‎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)