-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Define and document branch strategy for the spec, both development and publishing #3677
Comments
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. |
steps: dev branch (current main) - "starting point branch" (create other branches from this one) |
Henry - draft PR. |
from Karen: to summarize:
|
TODO: schema generation process. When do we publish schemas?
Karen: PR spec change, then follow up with a new PR for schema change. both consistent on dev branch! |
In a recent TDC call, we decided that the spec, schema, and gh-pages aspects have different priorities, and likely different people able/willing to work on them. I've split the schema and gh-pages aspects out as follows:
This issue will now only track the spec branching policy. |
I discovered something today that AFAICT is not written down anywhere, but I wish I'd known it as it would have made some of the 3.0.4/3.1.1 archaeology a bit easier: Each time a new vX.Y.Z-dev branch has been created, the previous versions So this means that we should create the new But this will preserve what we can, and once documented will make at least some diffs available that I struggled to figure out. |
Hmm... actually I may have figured out how to preserve the positive aspects of the publication process (connecting the published |
OK, having spent more time with it now that I've figured out some key things, I think I understand how this was supposed to work. And I feel a lot better about this- this repository was set up by smart people, and I've always been puzzled as to their goal. But now it makes a lot more sense. The original intentBasically, it was designed for a workflow in which there were never multiple release lines. If you never have parallel releases, it's fine to rename a file across each new branch because the actual development is (conceptually) linear, and the branch/file changes are just organizing the conceptual line and ensuring that the published spec is under the correct name. This explains why asking for a 3.0.4 was seen as... if not strange, then at least something that was not entirely in the plan. IIRC, deciding to do a 3.0.3 after having started 3.1.0 required a bit of discussion, too. In the diagram below, you'll see that that's where the first "pseudo-merge" occurred. Pseudo-mergesA "pseudo-merge" (a term I just made up) is a porting of commits from one file on one branch to another file on a different branch. This is what we want to eliminate, because it is not well-supported by In the diagram below, I have not made square commits for all of the porting between 3.0.4, 3.1.1, and 3.2.0, because that would be a dizzying mess of arrows in all directions. Instead, I've just treated it as if each release forward-pseudo-merged to the next one as it was released, which is close enough in concept. Simplified visualAll filenames not prefixed by a directory are under Square outlines are "pseudo-merges" (treating 3.0.4 -> 3.1.1 and 3.1.1 -> 3.2.0 as having one pseudo-merge each at the end of the earlier-numbered release, instead of the extremely complicated reality). Circular outlines are normal merges. gitGraph TB:
commit id:"add 1.2.md"
commit id:"Swagger 1.2"
commit id:"1.2 post-release fixes"
commit id:"1.2 link and license fixes"
commit id:"add 2.0.md"
commit id:"Swagger 2.0"
commit id:"Swagger 2.0 dev continued past release date"
commit id:"Swagger 2.0 numerous fixes/expansions"
commit id:"OAS 2.0"
commit id:"de-facto OAS 2.0.1"
branch OpenAPI.next order:1
commit id:"add mostly empty 3.0.md"
merge main type: HIGHLIGHT id:"add 3.0.md as a copy of 2.0.md"
checkout main
commit id:"de-facto OAS 2.0.2"
checkout OpenAPI.next
commit tag:"3.0.0-rc0"
commit tag:"3.0.0-rc1"
commit tag:"3.0.0-rc2"
commit id:"rename 3.0.md to 3.0.0.md"
checkout main
merge OpenAPI.next id:"merge 3.0.0.md to main" tag:"3.0.0"
branch v3.0.1 order:2
commit id:"rename 3.0.0.md to 3.0.1.md"
commit id:"3.0.1 work"
checkout main
merge v3.0.1 id:"merge 3.0.1.md to main" tag:"3.0.1"
branch v3.0.2-dev order:3
commit id:"rename 3.0.1.md to 3.0.2.md"
commit id:"3.0.2 work"
checkout main
merge v3.0.2-dev id:"merge 3.0.2.md to main" tag:"3.0.2"
branch v3.0.3-dev order:4
checkout main
branch v3.1.0-dev order:5
commit id:"rename 3.0.2.md to 3.1.0.md"
checkout v3.0.3-dev
commit id:"rename 3.0.2.md to 3.0.3.md"
commit id:"3.0.3 work"
checkout main
merge v3.0.3-dev id:"squash 3.0.3.md to main"
branch v3.0.4-dev order:8
checkout main
commit id:"update README" tag:"3.0.3"
checkout v3.1.0-dev
merge v3.0.3-dev type:HIGHLIGHT id:"pseudo-merge from 3.0.3"
commit tag:"3.1.0-rc0"
commit tag:"3.1.0-rc1"
checkout main
merge v3.1.0-dev id:"merge 3.1.0.md to main" tag:"3.1.0"
branch v3.1.1-dev order:6
commit id:"rename 3.1.0.md to 3.1.1.md"
commit id:"initial 3.1.1 work"
checkout main
branch v3.2.0-dev order:7
commit id:"rename 3.1.0.md to 3.2.0.md"
commit id:"initial 3.2.0 work"
checkout v3.0.4-dev
commit id:"rename 3.0.3.md to 3.0.4.md"
commit id:"3.0.4 work"
checkout v3.1.1-dev
merge v3.0.4-dev type:HIGHLIGHT id:"pseudo-merge 3.0.4 into 3.1.1"
checkout v3.0.4-dev
merge v3.1.1-dev type:HIGHLIGHT id:"pseudo-merge 3.1.1 into 3.0.4"
checkout main
merge v3.0.4-dev id:"merge 3.0.4.md to main" tag:"3.0.4"
merge v3.1.1-dev id:"merge 3.1.1.md to main" tag:"3.1.1"
checkout v3.2.0-dev
merge v3.1.1-dev type:HIGHLIGHT id:"pseudo-merge 3.1.1 into 3.2.0"
The good thing here is that, if you know what you're doing, there's more commit history available than previously thought. Although the squashed merges still obliterated a lot of history that would have been really helpful (and the branches that were squashed are long-deleted, unless someone has an un-pruned fork that has their last positions still available). The tricky part will be getting 3.1.1 and 3.2.0 history onto a single file that preserves maximum history. I think we just want to branch |
OK, I have thought about how to make the switchover. Here's a diagram with abbreviated history and the new proposal:
gitGraph TB:
commit id:"merge 3.0.2.md to main" tag:"3.0.2"
branch v3.0.3-dev order:7
checkout main
branch v3.1.0-dev order:8
commit id:"rename 3.0.2.md to 3.1.0.md"
checkout v3.0.3-dev
commit id:"rename 3.0.2.md to 3.0.3.md"
checkout main
merge v3.0.3-dev id:"squash 3.0.3.md to main"
branch v3.0.4-dev order:10
checkout main
commit id:"update README" tag:"3.0.3"
checkout v3.1.0-dev
merge v3.0.3-dev type:HIGHLIGHT id:"pseudo-merge from 3.0.3"
checkout main
merge v3.1.0-dev id:"merge 3.1.0.md to main" tag:"3.1.0"
branch v3.1.1-dev order:9
commit id:"rename 3.1.0.md to 3.1.1.md"
commit id:"initial 3.1.1 work"
checkout main
checkout v3.0.4-dev
commit id:"rename 3.0.3.md to 3.0.4.md"
checkout v3.1.1-dev
merge v3.0.4-dev type:HIGHLIGHT id:"pseudo-merge 3.0.4 into 3.1.1"
checkout v3.0.4-dev
merge v3.1.1-dev type:HIGHLIGHT id:"pseudo-merge 3.1.1 into 3.0.4"
checkout main
merge v3.0.4-dev id:"merge 3.0.4.md to main" tag:"3.0.4"
merge v3.1.1-dev 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 src/oas.md to 3.1.2"
checkout dev
branch v3.2-dev order:3
commit id:"update src/oas.md to 3.2.0"
commit id:"add Security Scheme deprecation"
commit id:"add Device Code authorization"
commit id:"add oauth2MetadataUrl"
commit id:"add ciba support"
The new approach starts from the release of 3.1.1 on
Note that I just left out the Path Item This gives us the proper relationship between 3.1.1 (as released) and both the I'll make a separate comment about how to release from these branches. |
OK here's how the new approach is proposed to work, starting from the tagged release of 3.1.1 on The following diagrams show:
No merges back to
|
If we need to do post-release work on released documents, we could do that on the Note that this proposal does not address schema development, which needs to be independent of the spec releases and is being tracked in #3716. |
Why do we need the |
@ralfhandl Please don't make a future me have to figure out that there was never a proper start and we just renamed things from version branch to version branch. Give that future repo archaeologist a sensibly-named branch that does what it seems to and provides the basis for all of the working branchs. Please. |
@ralfhandl another reason to have
|
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:
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:
oas.md
and this is the canonical spec version (so I guess onmain
it's the latest stable release? We didn't talk about that)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.oas.md
into themain
branch under theversions
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; theversions
andschemas
directories are just fine as they are, and the tagging can happen as it does now if we want to keep doing thatdev
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 fromv3.0.4-dev
dev
, with the correct contents from the existing release branches pulled over, branched accordingly (whatever we decide "branched accordingly" means)$id
and publish" workflow that... has some sort of problem with somethign?$id
which makes the publish workflow impossible right now, so...The text was updated successfully, but these errors were encountered: