Skip to content

Conversation

@ralfhandl
Copy link
Contributor

@ralfhandl ralfhandl commented Oct 21, 2025

As discussed in today's Overlays Meeting #172, use a simplified approach where everything happens on main with short-lived PR branches (preferrably in forks).

On release a spec version is moved from dev-versions to versions, preserving its commit history. Its schema and schema test folders are renamed and lose the -dev suffix.

Schema versions are in perpetual maintenance and start directly in the schemas folder.

Commit c4a5c3e adds file dev-versions/1.1.0.md which is an adjusted copy of versions/1.0.0.md:

$ diff ./dev-versions/1.1.0.md versions/1.0.0.md 
7c7
< ## Version 1.1.0
---
> ## Version 1.0.0
284d283
< | 1.1.0 | TBD | Release of the Overlay Specification 1.1.0 |

Commit 1328218 adds folder schemas/v1.1-dev which is an adjusted copy of schemas/v1.0:

diff schemas/v1.1-dev/schema.yaml schemas/v1.0/schema.yaml
1c1
< $id: https://spec.openapis.org/overlay/1.1/schema/WORK-IN-PROGRESS
---
> $id: https://spec.openapis.org/overlay/1.0/schema/WORK-IN-PROGRESS
3c3
< description: The description of Overlay v1.1.x documents
---
> description: The description of Overlay v1.0.x documents
8c8
<     pattern: ^1\.1\.\d+$
---
>     pattern: ^1\.0\.\d+$

and similar adjustments in file README.md.

It also adds folder tests/v1.1-dev which is an adjusted copy of tests/v1.0, the only difference being the value of the overlay field in the pass and fail test cases, for example

diff tests/v1.0/fail/actions-invalid-description.yaml tests/v1.1-dev/fail/actions-invalid-description.yaml
1c1
< overlay: 1.0.0
---
> overlay: 1.1.0

It also adjusts related scripts and workflows:

  • .github/workflows/schema-publish.yaml has an adjusted branch name and an updated list of reviewers
  • scripts/schema-publish.sh skips folders for schemas under development with suffix -dev
  • tests/schema.test.mjs moved to the parent folder and now loops over all schema version folders

Commit d29c651 updates section "Branching Strategy" in CONTRIBUTING.md and describes the new setup.

@ralfhandl ralfhandl marked this pull request as ready for review October 21, 2025 16:39
@ralfhandl ralfhandl requested review from a team as code owners October 21, 2025 16:39
- v1.1-dev schema versions
- one test script looping over all schema versions
- publishing script skips dev schema versions
baywet
baywet previously approved these changes Oct 21, 2025
@ralfhandl
Copy link
Contributor Author

I think I covered everything now in the added CONTRIBUTING.md

@ralfhandl ralfhandl requested a review from baywet October 21, 2025 17:13
baywet
baywet previously approved these changes Oct 21, 2025
@ralfhandl ralfhandl changed the title Start 1.1.0 from 1.0.0 Start 1.1.0 from 1.0.0 with simplified branch setup Oct 21, 2025
@baywet baywet mentioned this pull request Oct 21, 2025
5 tasks
Copy link
Contributor

@mikekistler mikekistler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! 👍

@ralfhandl ralfhandl merged commit fe24d3c into OAI:main Oct 27, 2025
3 checks passed
@ralfhandl ralfhandl deleted the main-add-v1.1 branch October 27, 2025 18:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants