Describe new spec branch and file layout

[handrews]

With related process tweaking.

View the file as rendered markdown to see a diagram of the branching strategy!

[ralfhandl]

One minor nit, one question

[miqui]

Pending @ralfhandl comment, so far looks good to me. @handrews mermaid is awesome. Thanks for the suggestion.

[lornajane]

My only question here is how to update the longer lived branches (such as v3.2-dev) with other changes that arrive in the main branch. The minor release branches could be quite long-lived, so we might want to bring housekeeping type changes such as updated contributor guidelines, tooling changes like GitHub actions, or even just keep the updates to the versions/ folder available in the same branch.

I propose one additional step of allowing updating the minor release branches (and therefore maybe also dev ?) onto main as needed. I guess we can't rebase, since there might be work in flight based off those branches, so it might be as simple as merging main into these per-version branches. If I understood the rest of the proposal, these branches should really only have changes to the spec file, and the main branch doesn't contain that file, so I hope it won't be too much chaos.

[handrews]

@lornajane I think we should figure out what the purpose of the different branches really is.

I don't think there's any need to keep anything updated on the spec branches. That's not a hill I plan to die on, but I caution against making things more complex than they need to be. The spec branches are for the spec (and maybe the schemas, depending on how that issue is decided).

What else is there?

• General process documentation? That should live in the OAI/community repo (some files are already duplicated there)
• Examples? Already being moved to the Learn site
• The build and test stuff? All of that really needs to be moved to its own repo to be shared across OAS/Arazzo/Overlay/etc., and then it could be submoduled into wherever it is needed
• Development process docs? This is the only thing that arguably needs to stay

New question

[ralfhandl]

What else is there?

• proposals
• EDITORS.md
• MAINTAINERS.md

[handrews]

@ralfhandl I considered EDITORS.md and MAINTAINERS.md to be some combination of process documentation and build script.

Arguably, the proposals/ tree should move to dev and not be on main. The main branch should be for publishing, not development.

[handrews]

Probably most of the debate here really comes down to the purposes of the branches and repositories. In my view:

• The genearl process documentation, including both common-to-all-specs development procedures and lists of people and roles that are not significant to the build scripts, needs to move to the OAI/community repository. One process doc has already moved, and the .md file here just points to that repo. We should finish this migration.
• The spec site needs to be in its own repo (we already decided to do this, it's just stalled, see Move gh-pages into main branch #3868)
• The build system needs to be factored out into its own repository that can be shared among all specification repos - obviously a few things are repository-specific, but most of it is not (even the legacy hacks for dealing with old OAS versions should be part of the build repo, not the OAS repo)
• main should be the stepping-stone to publishing, but not the authoritative published documents. Anything on main should have an authoritative rendering on spec.openapis.org (specs, schemas, SECURITY_CONSIDERATIONS.md)
• dev should be about general development, and the base for all release lines. Non-version-specific proposals (and the source for SECURITY_CONSIDERATIONS.md, I suppose) should live here, and not on main because they are not published to spec.openapis.org
• X.Y-dev should be about the spec (and most likely schemas, but see Schema development: main or branch, in parallel or at release time? #3716)
• X.Y.Z-rel should just be renaming to keep the history, and maybe post-publication fixes if we ever have to do them again, although maybe that could go on main like in the past, idk

[lornajane]

Having less "other" things here is definitely going to help! However I'd still advocate for CONTRIBUTING file updates, plus new versions, to be available on those dev branches. I'd love to reason this use case away but I think it'll still happen to us ... could we formalise that we can merge main to dev (edit: this should say dev and *-dev I think) for good reasons but not for fun?

[handrews]

@lornajane I don't completely object to merging things up from main. I think we should consider whether something like CONTRIBUTING.md properly lives on main or dev (and by "lives" I mean "the place where we make changes").

What I want to avoid is anything that gets changed in multiple places and has to have those changes merged in multiple directions.

Spec:

• Primarily lives on dev, where it is updated with certain releases as explained below (we'll have to decide what we're doing about 4.0 when we get there) but not otherwise changed here at all!
• Most work occurs on vX.Y-dev branches (PR branches come from and are merged to here)
• vX.Y.Z-rel branches are only used to rename the file and maybe for emergency post-publication fixes (TBD if and when it becomes an issue)
• vX.Y.0-rel is branched from the same vX.Y-dev commit that is also merged to dev for keeping the dev branch up-to-date with minor releases
• Optionally, we could also merge X.Y.Z patch releases from the most recent active line to dev. This might be a better answer to @ralfhandl 's "why don't we merge patch releases" question. See diagram in next comment for more on this idea
• I'd like to have a clear accounting of what lives on main (and is merged out to other branches, and never in) and why those things are not managed from dev - Is there really any work that should be done on main, and if so, why?

[handrews]

Here's an alternative diagram with a few improvements.

NOTE: Mermaid will only do 8 colors round-robin, so please ignore that main and dev match the colors of other branches as it is an unintended coincidence. The 3.1.x branches are yellow, the 3.2.x branches are blue, and 3.3.x pink.

• Whenever a vX.Y.Z-rel branch is created, the same commit that is the base of that branch is:
  • merged up to the vX.Y+1-dev (if it exists)
  • merged down to dev if and only if Z == 0 or X.Y.0 is the most recent minor release

---
config:
  themeVariables:
    git0: "#5588bb"
    git1: "#cc8899"
    git2: "#eedd88"
    git3: "#ccbb66"
    git4: "#aa9944"
    git5: "#887722"
    git6: "#99ccff"
    git7: "#77aadd"
    git8: "#5588bb"
    gitBranchLabel1: "#000000"
    gitBranchLabel2: "#000000"
    gitBranchLabel3: "#000000"
    gitBranchLabel4: "#000000"
    gitBranchLabel5: "#ffffff"
    gitBranchLabel6: "#000000"
    gitBranchLabel7: "#000000"
---
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:6
  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"
  checkout v3.2-dev
  merge v3.1-dev id:"merge 3.1.2 fixes"
  checkout v3.1-dev
  branch v3.1.2-rel order:3
  commit id:"rename src/oas.md to versions/3.1.2.md"
  checkout dev
  merge v3.1-dev id:"update dev with active line patch release"
  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.3 fixes before releasing"
  checkout dev
  merge v3.1-dev id:"update dev with last pre-minor release patch release"
  merge v3.2-dev id:"update dev with minor release"
  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:7
  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"
  checkout dev
  branch v3.3-dev order:9
  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"

  checkout v3.1-dev
  commit id:"a 3.1.4 fix"
  checkout v3.2-dev
  commit id:"a 3.2.1 fix"
  merge v3.1-dev id:"merge 3.1.4 fixes before releasing"
  checkout v3.3-dev
  merge v3.2-dev id:"merge 3.1.4 / 3.2.1 fixes"
  checkout dev
  merge v3.2-dev id:"merge patch from active release line"
  checkout v3.1-dev
  branch v3.1.4-rel order:5
  commit id:"rename src/oas.md to versions/3.1.4.md"
  checkout v3.2-dev
  branch v3.2.1-rel order:8
  commit id:"rename src/oas.md to versions/3.2.1.md"
  checkout main
  merge v3.1.4-rel tag:"3.1.4"
  merge v3.2.1-rel tag:"3.2.1"
  checkout v3.2-dev
  commit id:"update version in src/oas.md to 3.2.2"
  checkout v3.3-dev
  commit id:"3.3 work"

Loading

[lornajane]

Action is with @handrews to implement this as written!