OpenAPI-Specification icon indicating copy to clipboard operation
OpenAPI-Specification copied to clipboard
verified publisher icon OAI

v3.0: set up schema maintenance

Open ralfhandl opened this issue 5 months ago • 6 comments

Prepare development branch for v3.0 schema maintenance:

  • [x] create branch v3.0-dev-wip - diff to dev
  • [x] delete src/oas.md - we do not plan a 3.0.5 spec release
    • [ ] otherwise: #5094
  • [x] delete src/schemas/validation/*
  • [x] move _archive_/v3.0/schemas/schema.yaml and accompanying README.md to src/schemas/validation/
  • [x] move test-related files from _archive_/v3.0/schemas/ to tests/
  • [x] make tests work and pass
  • [x] refactor tests to use same tools as the v3.1 tests
  • [x] test schema publishing workflow - also works for 3.0
  • [x] adjust selected 3.1 pass/fail test cases to increase schema coverage
  • [ ] rename branch v3.0-dev-wip to v3.0-dev (or squash-merge it into a branch freshly created from dev)

ralfhandl avatar Sep 23 '25 09:09 ralfhandl

@ralfhandl we have not resolved #4865 regarding a 3.0.5 or errata, and I am still concerned about 3.0.4 misleading tooling developers and complicating the upgrade path. We should not do anything to preclude a 3.0.5 at this time.

handrews avatar Sep 23 '25 15:09 handrews

I don't think we should commit to maintenance for EOL branches.

lornajane avatar Sep 23 '25 15:09 lornajane

I'm still not giving up on fixing the accidental but egregious errors (giving the completely wrong instructions on handling URI percent-encoding in header parameters, for example, in ways that will cause tooling incompatibilities) in 3.0.4.

handrews avatar Sep 23 '25 15:09 handrews

@lornajane @ralfhandl of course if we solve the 3.0.4 issues with errata instead of a 3.0.5, we could hot-patch the errata links on main rather than having a v3.0-dev (as we could, in theory, hot-patch a schema fix somehow if we want to). Anyway, that debate belongs in #4865, I just replied here because @lornajane brought up the broader philosophical point here.

handrews avatar Sep 23 '25 15:09 handrews

I think we should enable @karenetheridge to fix bugs in the 3.0 schema.

I do not want to preclude a 3.0.5 spec release, nor do I want to encourage it.

Having no spec source file in the 3.0 schema maintenance branch seems a good middle ground that allows both possible futures.

ralfhandl avatar Sep 23 '25 15:09 ralfhandl

@lornajane @ralfhandl let's take this broader discussion to #4865. I will write an updated summary of my position there.

handrews avatar Sep 23 '25 15:09 handrews