Define and document branch strategy for the spec, both development and publishing

[handrews]

This issue consolidates the various interrelated branch / merge / publish / etc. we need to sort out, as discussed in the Moonwalk 19 March and TDC 21 March meetings. This needs to cover:

• Specification development
• Specification release / publishing
• Schema development
• Schema release / publishing
• Any additional publishing currently handled through GitHub pages (the gh-pages branch) such as registries

[EDIT: Schema (#3716) and gh-pages (#3717) have been split out into their own issues.]

I've included notes from the meeting below, followed by my own thoughts.

---

@lornajane's notes from the 21 March 2024 TDC meeting:

We also talked about our git versioning/branching/development workflow and it's clear that we are in need of a change. A fruitful discussion seems to have happened this week in the Moonwalk SIG meeting. A high-level summary of what I understood would be:

• there is one file in the repository called oas.md and this is the canonical spec version (so I guess on main it's the latest stable release? We didn't talk about that)
• we maintain one branch for 3.0, where oas.md is under active development and will become the 3.0.4 release. The branch will be tagged at release time. The same pattern for a 3.1 branch where the next tag would be 3.1.1 and a 3.2 branch where we'll tag 3.2.0.
• when we tag a new version, we also copy the oas.md into the main branch under the versions structure that we have now.

The advantages of this structure are that we can diff the different versions and revisions of the same file in a sane way. There are fewer branches to keep track of so things should be easier to reason about. And it gives a simpler workflow for adding versions (hello 4.0) as we move forward.

My questions: where are we having the discussion about this that isn't in an agenda comment thread? And how do we apply changes such as tooling updates to the minor version branches without affecting the oas.md file? /cc @miqui since I know you're putting something together on this.

As a followup to getting the branches sorted, at some point we can change our use of github pages - currently it uses a branch, which was a very early implementation. We think it would be more useful to use a subfolder now.

---

My thoughts:

• main is where officially published / publishable things live; the versions and schemas directories are just fine as they are, and the tagging can happen as it does now if we want to keep doing that
• I'd recommending initializing a new dev branch purely to serve as the base for this new process. This should include the work-in-progress development directory / files that aren't published, and therefore don't appear on main, initialized from v3.0.4-dev
  • I'd then recommend new release branches, branched from dev, with the correct contents from the existing release branches pulled over, branched accordingly (whatever we decide "branched accordingly" means)
  • I'd strongly advise against anything more complicated; e.g. we do not need "feature branches" as we're not big enough, and folks should work in their forks rather than branching the main repo because the branch list here is confusing enough as it is
  • We also still need to decide if we're keeping GitHub as the cite-able source of truth or if we want the pretty HTML to take that over
• We need to think through how we want schema development to happen.
  • We create one schema per minor release, and allow them to change independent of the spec, so the workflow is different
  • We should decide when to do schema work (while we change the spec? only when we release?) and enforce it strictly
  • We need to sort out the "update $id and publish" workflow that... has some sort of problem with somethign?
  • Some schemas don't have $id which makes the publish workflow impossible right now, so...
  • We still need to figure out how to publish schema changes (see also Host schema publicly #151 and npm package not published? #2400)
• We need to think through how we want the registries to work
  • The whole point is that they're easier to change at any time than the spec, or even the schemas as there is no publishing process other than merging
  • Do we still need GitHub pages or should the registries go with the learn site?

[lornajane]

Yes, all of this. I'm not sure I have enough of a handle on the current state of play to comment on the plans for initialising - and since we need to do new releases and get those into main, I'd be tempted to branch at that point.

Do the registries update with reference to the schema versions? I think they should stay in this repo and be tied to spec changes, but it's not clear if we can update them more easily if they get changes that match spec changes, or not.

[miqui]

steps:
1st - modify developers.md to describe the new reality.

dev branch (current main) - "starting point branch" (create other branches from this one)

[miqui]

Henry - draft PR.

[miqui]

from Karen:

to summarize:

• consistent filename across branches (for spec, schema files etc)
• 3.1.1-dev branch renamed to 3.1-dev; 3.0.4-dev branch renamed to 3.0-dev; there will be a 3.2-dev branch that may also merge changes that are added to 3.1-dev
• when a version is released, it is copied into subdirectories in the main branch; web publishing done from main
• small fixes only to 3.0.x and 3.1.x; spec-impactful changes to 3.2

[miqui]

TODO: schema generation process.

When do we publish schemas?
Work in parallel or at the end of the spec change?

• current status: unknown (potentially not aligned)

Karen: PR spec change, then follow up with a new PR for schema change.

both consistent on dev branch!