Define deployment process for link fixes to published specifications

[handrews]

In past TDC meetings (going back as far as March 2023), the @OAI/tsc has decided that broken links (broken because other entities that should not break their links in fact do break them) can be fixed in a deployed specification.

We now need to decide and document how this actually works, in order to get the numerous link fixes that have been submitted (and in some cases merged) published.

Note: I just realized we don't seem to have an issue to track this, or at least I can't find it. Please close as a dup if I missed one.

[handrews]

@baywet were you the person who had some info in Thursday's call on what we could do with tags?

[lornajane]

Document that we can make this category of edit (alongside typos and formatting changes) without a version bump, and then go ahead and make it. Am I missing something here?

[handrews]

@lornajane there's... something to do with github tags? I really don't understand it. My impression was that the important thing for others citing the specs is that the canonical URL does not change, and the contents do not change in any way (we determined that links that broke for reasons outside of our control are not really "contents", but even the most trivial formatting or typo fixes are changes in contents). Maybe the tags are supposed to match what's on main for each release? But they are already out of sync because we merged the RFC 3339 and SPDX link fix changes.

[baywet]

@handrews yes. For this answer please keep in mind I don't have much context on:

• what are the links we don't want to break while updating their content (examples appreciated)
• how are they published at the first place (waiting on @webron to provide information on that process I think as I'm assuming it's the same that refreshes the website)

I did some poking around and it doesn't look like long lived branches are used here (BTW, there are a bunch of stale branches from merged/closed PR, if someone has write permissions, it'd be a good thing to delete them for sanity)

When looking at the tags, it looks that tags are created once, and never touched again (from looking at their creation dates)

If the links we don't want to break but update their content rely on tags (like this for example https://raw.githubusercontent.com/OAI/OpenAPI-Specification/3.1.0/schemas/v3.0/schema.json ) we could just retag things. That assumes we don't have some specific tooling that relies on commit hashes, but in my experience that's extremely rare.

Here is a script to tweak depending on the scenario

# create a branch from the tag
git switch -c newVersionOfTheTag tag

# get the commits we need into this new branch
# we could alternatively checkout specific files, perform merges, it really depends on what we want to select
# more discussion here to have as the devil is in the details
git cherry-pick AllTheCommitsYouCareAbout

# deletes the tag locally
git tag -d tag

# deletes the tag on remote
git push origin :tag

# recreates the tag locally
git tag Tag

# publishes the tag
git push --tags

Note: the last 3 commands need to be run quickly as the link will be dead in between.

Note: we could create two branches at the beginning, one without the changes, and another with the additional changes, so a pull request could be used to verify what we're changing.

[handrews]

Thanks @baywet! I added both the "can we just re-tag because it seems likely to be what we want" question and your question about old branches to this Thursday's TDC agenda.

[notEthan]

man git-tag has some to say on re-tagging. The suggestion here is what is described there as "The insane thing". It will end up with the countless clones of this repository having inconsistent tags (because git pull doesn't overwrite already-created tags).

[baywet]

Thank you for adding this context I didn't outline clearly in my original message. This is what I was eluding to with that sentence:

That assumes we don't have some specific tooling that relies on commit hashes, but in my experience that's extremely rare

Again, context on what we're trying to achieve is missing, but assuming we need to overwrite tags, it's possible, whether we should do it or not remains a question.

Arguably long-lived branches would be a better option, which is what I suggested on the call

[lornajane]

I'm not sure I have all the context here but re tagging is usually confusing, so I would urge that we try to avoid strategy that needs it

[baywet]

Collecting some notes about the chat we've had during today's TDC's meeting with @webron @lornajane @handrews and others.

The specs websites is effectively a GitHub pages websites with a custom domain. The content is served from the gh pages branch.

Every time something gets merged to main, this workflow creates a PR after running respec

(see this example https://github.com/OAI/OpenAPI-Specification/pull/3520)

For validation purposes, we could update that workflow with:

1. trigger on PRs to main.
2. add a filter on the create pull request step so it only executes on push to main.
3. add a new upload artifact step so we have the generated HTML available to download and browse locally.
4. (opt) we could also add additionally add validations like git diff, html validators, etc... to that workflow

What we didn't come to the bottom of are the tags: from looking at the scripts/workflows, they are not used to refresh the pages. It sounds they are only here for "archival" aspects. Why are we using multiple version documents as opposed to a single one and rolling tags/long term branches is not clear, but it could be to reduce the complexity of the publishing workflow. More discussions required on this aspect.

[lornajane]

I vote we patch release the 3.x versions instead of updating git tags (this way lies madness, I promise). I thought we were patching 3.0 and 3.1 anyway with clarifications, and I don't feel strongly about updating all the possible past patch releases.

[baywet]

how do we feel about a single file, but instead of using tags we'd use long term branches? it'd be using git in a more appropriate way, require less git-fu, etc... (support/spec-2.X, support/spec3.1.1 etc...)

[handrews]

@lornajane the only "patches" on the published files are fixes to broken links that broke because whoever owns the target moved it somewhere else, and that's where the tags are relevant. We are not allowing anything else on the published versions.

The rationale is that the published contents need to stay exactly the same but 3rd-party link URLs aren't "content". The content is "pointer to document X" so keeping the pointers working is preserving the original content, not changing it.

I'd say "hopefully this will be rare" but three different link target owners (GitHub, IETF, and whoever manages SPDX) moved documents on us in the last year or two, so... ¯\(ツ)/¯

---

@baywet using a single active file with branches would make it easier to manage multiple releases lines like we now plan to do. Since I'm looking right now at how to sync up the 3.0.4, 3.1.1, and 3.2.0 branches, I'd be much happier if we could use normal git tools for it.

In the past, we only ever worked on one at a time, so the way things are arranged made more sense. But we're taking a different approach to release lines now. Perhaps it is time for a change.

[miqui]

Proposal: Last patch release: 3.0.4 - @lornajane - TODO.

[miqui]

3528 #3529. (reference)

Policy issues. Product doc?

[lornajane]

After further discussion, we agreed that the published spec versions should be and remain immutable. We'll fix the links in the next releases, and leave the published ones unchanged.

[karenetheridge]

Would that imply that there will be more frequent spec releases, in order to accommodate schema fixes? e.g. 3.1.2 might soon follow 3.1.1?

[lornajane]

Yes, that's the plan. "Soon" will be relative, but I'm confident we can improve on the past release cadence.