-
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. |
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: