Schema development: main or branch, in parallel or at release time?

[handrews]

I'm splitting out the schema-related concerns from #3677 as we decided in a recent TDC meeting that the schema, spec, and gh-pages parts have different priorities (and probably involve different people).

• New schemas are created for each minor or major release
  • Patch releases are limited to changes that would not require a separate schema for each patch release in a minor release line
  • Should new minor/major schemas be created and updated in parallel with spec changes, or deferred and created all at once just prior to the release, as part of the final review effort?
  • If created and updated in parallel, this should be integrated with the development branch process being sorted out in Define and document branch strategy for the spec, both development and publishing #3677, presumably continuing to be published to main in the current schemas/, just as Define and document branch strategy for the spec, both development and publishing #3677 recommends publishing the markdown to the current versions/ location
• Schemas can currently also be changed for bug-fixing or functional improvement at any time, and released independently from the release schedule (see also Define and document our schema publishing process #3715)
  • This includes but is not limited to patch release-related bug fixes
  • This might require a different tagging strategy from whatever we do for spec releases

[handrews]

So... given the proposals for branching in PR #4154 (background in issue #3677), I can see a few options for schemas:

share the X.Y-dev branches, but release independently

This would consolidate the schemas, based on the 3.1.1 files, under src/ (alongside the spec which is src/oas.md) on the dev branch, and we'd do the release-line-specific schema work on the appropriate X.Y-dev branch.

Since schema releases are independent of patch releases, instead of making X.Y.Z-rel branches to rename to the published file location, we'd make branches like 2024-10-22-rel.

PROS:

• Same process and working branches as the spec
• We can merge changes across release lines
• This allows simultaneous spec and schema changes (which is a surprisingly controversial proposal, but I'm putting it under "PRO" based on personal preference)

CONS:

• The release branches are a bit unwieldy, and schemas might be published significantly more often (it's a bit hard to say, and also depends on how define the scope of schemas — see Consider allowing contributions to "linting" schemas #4141 and Improve 3.1+ schema $id UX #4147)

MITIGATION:

• We could probably automate more of the publishing process

Keep the schemas/ layout but do the work on dev

PROS:

• No renaming for release needed
• We can still batch up changes on dev and only merge them to main when we want them published

CONS:

• Schema dev is still divorced from the spec changes that drive it (which I consider a con)
• No merges, we'd have to do git --format-patch | sed | git am -3 hackery still
• Different process to remember compared to spec work

MITIGATION:

• Schemas changes usually aren't so complicated, so manually psuedo-merging isn't quite as horrible

Hybrid 1: Keep /schemas but work on X.Y-dev

In this approach, we don't rename any schema files into the src/ directory.

PROS:

• Spec and schema changes can be in the same PR
• The fundamental branching pattern is the same (just not the file management pattern)

CONS:

• The file management pattern is different
• Still require psuedo-merge messiness

MITIGATIONS:

• Pseudo-merges of schemas aren't as horrible

Hybrid 2: work on X.Y-dev under src/ and release directly from there

This approach more-or-less abandons schemas on dev or main, and just triggers publishing to the spec site directly from the X.Y-dev branch.

PROS:

• Same structure/process as the spec
• No release branches needed
• Changes can merge across release lines
• No weird-looking semi-published schemas on main

CONS:

• Schemas harder to find? Do we leave the old schemas on main?
• No ability to batch up changes if we automatically trigger publishing from X.Y-dev

[lornajane]

We reached a consensus that Hybrid 2 would work well for most people. We will need to take care to provide good development experience to be able to quickly build and try things.

@handrews has the action point to implement this.