How to create a new version dev branch such as v3.3-dev?

[ralfhandl]

According to Branching and merging (3.1.2, 3.2.0, and later) we will create branch v3.3-dev from dev, despite the fact that

• src/oas.md
• src/schemas/**
• tests/schema/**

are hopelessly outdated on dev and the current content of v3.2-dev is the actual semantic starting point for 3.3 development.

Shouldn't we rather create v3.3-dev from v3.2-dev?

[handrews]

@ralfhandl I think there's an error in the diagram which shows the release branches merging to main, then main to dev, and then dev to each new X.Y-dev. But really when we create a release branch from the latest active release line (in this case v3.2.0-rel) we should also merge that down to dev to update the src tree, and then branch v3.3-dev from dev. Only v3.2.0-rel would merge to main.

The idea was to keep dev more-or-less in-sync with the most current release line.

[ralfhandl]

The idea was to keep dev more-or-less in-sync with the most current release line.

That is tricky because changes to dev are auto-synced to all vX.Y-dev branches.

[ralfhandl]

@handrews Maybe we need to more precisely define what we mean by a "release branch". I see two possibilities:

1. A snapshot of the vX.Y-dev branch at the moment we release, containing the src folder and other files that only exist in "dev" branches.
2. A branch containing the changes that we want to merge into main, with a new markdown file in versions and not containing the src folder and other files that only exist in "dev" branches.

If it is the first, we can create the new vX.Y-dev branch from it (with the same result as creating it from the previous vX'.Y'-dev branch). Then we need a temporary branch without the dev-branch-specific stuff for merging the released spec into main.

[ralfhandl]

We actually already define that we mean #2:

• vX.Y.Z-rel is the release branch for an X.Y.Z release (including when Z == 0). It exists primarily for git mv-ing src/oas.md to the appropriate versions/X.Y.Z.md location before merging back to main, and can also be used for any emergency post-release fixes that come up, such as when a 3rd party changes URLs in a way that breaks published links.

In addition to moving and renaming the spec source file we also need to remove any files that we don't want to bring to main, which we should mention in this part of CONTRIBUTING.md.

[handrews]

@ralfhandl it is definitely #2, so yes, we should update that in CONTRIBUTING.md.

I would still prefer to merge the latest release from the latest release line (the v3.2-dev release line branch, at the point where the v3.2.0-rel release branch is made) back to dev, because that makes dev the last known good development state. Which is what I think dev should be, along with shareable infrastructure. But I have not thought all of this through in the light of our experience so far, so perhaps this is not the most workable idea.

We should also consider that all of the infrastructure should be out in its own repo. Currently dev is doing double-duty as an infrastructure branch that needs propagating, and that is what is making our branch management so complex (and our PRs absolutely clogged with constant sync PRs- when I came up with this I did not anticipate us leaving the infrastructure in the repository as we have been talking about factoring it out since before then. If I had realized that we would not, I might have suggested a different arrangement).

[ralfhandl]

We paused the infrastructure refactoring back in March/April to focus on 3.2.0 and 3.1.1.

We now seem to have two possibilities:

1. Finish the infrastructure refactoring before creating v3.3-dev.
2. Create v3.3-dev directly after releasing 3.2.0, pragmatically branch it off v3.2-dev, and leave dev untouched for now.

[ralfhandl]

Shouldn't we rather create v3.3-dev from v3.2-dev?

The text actually says exactly that:

• Post-release steps:
  • If this was a major or minor release (Z == 0), branch vX.Y+1-dev from vX.Y-dev

I apparently was misled by the diagram where dev and v3.3-dev have the same color 🙄

[handrews]

@ralfhandl GitHub/Mermaid only allows a limited number of colors, sadly. I actually put:

Release lines are grouped by color, although the colors of dev and main are not significant as these diagrams are limited to only 8 colors.

above the diagram for that reason, but maybe it could be made more clear? idk.

[ralfhandl]

Removed 3.1.4 in

• main: simplify branch diagram in CONTRIBUTING.md #5009

Coloring is less confusing to me: v3.3-dev and dev have different colors now, which shows that v3.3-dev is branched from v3.2-dev.