Skip to content

Describe new spec branch and file layout#4154

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lornajane merged 4 commits into from
Oct 31, 2024
Merged

Describe new spec branch and file layout #4154

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
281b6e9
Describe new spec branch and file layout
handrews Oct 23, 2024
0d061e9
Fx typo, add link
handrews Oct 23, 2024
e0df121
Further clarify branching/merging
handrews Oct 23, 2024
d6de1c0
Update CONTRIBUTING.md
ralfhandl Oct 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 100 additions & 13 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -14,26 +14,113 @@ If in doubt about a policy, please [ask on our Slack](https://communityinviter.c

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.

### Current branches and documents open to change
### Changing the schemas

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.
Schemas are only changed _after_ the specification is changed.
Changes are made to the YAML versions on the `main` branch.
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.

The current (31 July 2024) active releases are:
### Authoritative source of truth

| Version | Branch | File | Notes |
| ------- | ------ | ---- | ----- |
| 3.0.4 | `v3.0.4-dev` | `versions/3.0.4.md` | Soon to be published |
| 3.1.1 | `v3.1.1-dev` | `versions/3.1.1.md` | Soon to be published |
| 3.2.0 | `v3.2.0-dev` | `versions/3.2.0.md` | Planned for late 2024 |
| 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 |
The [spec site](https://spec.openapis.org) is the source of truth.

### Changing the schemas
This changed in 2024, as the markdown files on `main` do not include certain credits and citations.

## Development and publication process

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.
Comment thread
ralfhandl marked this conversation as resolved.

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

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

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

### Branch diagram (3.1.2, 3.2.0, and later)

Initial steps:

* `dev` branches from `main` at the 3.1.1 release commit
* Each `X.Y-dev` branches from `dev`

Upon release:

* Each `X.Y.Z-rel` branches from the corresponding `X.Y-dev`
* After renaming `src/oas.md`, `X.Y.Z-rel` merges to `main`
* Publishing to the [spec site](https://spec.openapis.org) is triggered by the merge to `main`

Initiating the next minor release after releasing `X.Y.0`:

* 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
* This `X.Y.0` commit on `dev` is the base of `X.Y+1-dev`

Other notes:

* Patch releases are _not_ merged to `dev`

```mermaid
gitGraph TB:
commit id:"merge 3.1.1.md to main" tag:"3.1.1"
branch dev order:1
commit id:"rename 3.1.1.md to src/oas.md"
branch v3.1-dev order:2
commit id:"update version in src/oas.md to 3.1.2"
checkout dev
branch v3.2-dev order:5
commit id:"update version in src/oas.md to 3.2.0"
commit id:"some 3.2.0 work"
checkout v3.1-dev
commit id:"a 3.1.x fix"
branch v3.1.2-rel order:3
commit id:"rename src/oas.md to versions/3.1.2.md"
checkout main
merge v3.1.2-rel tag:"3.1.2"
checkout v3.2-dev
commit id:"more 3.2.0 work"
checkout v3.1-dev
commit id:"update version in src/oas.md to 3.1.3"
commit id:"another 3.1.x fix"
checkout v3.2-dev
commit id:"still more 3.2.0 work"
merge v3.1-dev id:"merge 3.1.x fixes before releasing"
checkout v3.1-dev
branch v3.1.3-rel order:4
commit id:"rename src/oas.md to versions/3.1.3.md"
checkout v3.2-dev
branch v3.2.0-rel order:6
commit id:"rename src/oas.md to versions/3.2.0.md"
checkout main
merge v3.1.3-rel tag:"3.1.3"
merge v3.2.0-rel tag:"3.2.0"
Comment thread
ralfhandl marked this conversation as resolved.
checkout dev
merge v3.2-dev id:"update dev with minor release"
branch v3.3-dev order:7
checkout v3.1-dev
commit id:"update version in src/oas.md to 3.1.4"
checkout v3.2-dev
commit id:"update version in src/oas.md to 3.2.1"
checkout v3.3-dev
commit id:"update version in src/oas.md to 3.3.0"
```

### Schema development

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

#### Active branches

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.

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

## Authoritative source of truth
The current (20 October 2024) active specification releases are:

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

## Style Guide

Expand Down
11 changes: 6 additions & 5 deletions README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -37,18 +37,19 @@ Looking to see how you can create your own OpenAPI definition, present it, or ot
## Participation

The current process for developing the OpenAPI Specification is described in
[Development Guidelines](DEVELOPMENT.md).
the [Contributing Guidelines](CONTRIBUTING.md).

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`.

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/embed?src=c_fue82vsncog6ahhjvuokjo8qsk@group.calendar.google.com) online.

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:

* Review the [current specification](versions/3.1.0.md). The human-readable markdown file _is the source of truth_ for the specification.
* Review the [development](DEVELOPMENT.md) process so you understand how the spec is evolving.
* 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.
* 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.
* Review the [contributing](CONTRIBUTING.md) process so you understand how the spec is evolving.
* 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.
* Subscribe to an open issue a day (or a week) in your inbox via [CodeTriage.com](https://www.codetriage.com/oai/openapi-specification).
* Create an issue to describe a new concern. If possible, propose a solution.
* Create a discussion to describe a new concern, ideally with clear explanations of related use cases.

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

Expand Down