Should we-organize our GitHub pages to a directory on main?

[handrews]

Splitting this out from #3766, to which it is still somewhat related as we should consider the impact on how many PRs to how many different branches are required for a change that spans the spec and the registries.

Originally, gh-pages sites needed to be on a gh-pages branch that (as ours does) typically has a completely different layout than main. That is no longer required, and it is much more common to deploy from a directory on main. Or at least from a directory on a branch that is no more different from main than any other working branch.

[Bellangelo]

I totally agree with this one. This might be a personal preference but I usually find it confusing when each branch is a different project completely. I can start with this one after this is closed #1823

[handrews]

Note that the current build process seems spread across both main and gh-pages, plus duplication for the OAS and Arazzo specs, which probably needs to be unraveled.

Also, there are infrastructure bits under the curren top-level directory on main which should probably be pushed down into the directory that will replace the gh-pages branch to reduce clutter.

[frankkilcommins]

We should consider having a dedicated repo for spec.openapis.org? As we have now moved to a multi-specification project (and likely more coming - Overlays), nesting the website housing the specs under one of the specification repos is a little confusing.

Each separate specification repo that wants to publish can issue PRs to the repo housing the HTML versions and other information relevant to spec.openapis.org. We could then have the same process in place for both OpenAPI-Specification and Arazzo-Specification repos.

[Bellangelo]

@frankkilcommins Should each spec has its own domain maybe? For example, arazzo.openapis.org, overlays.openapis.org etc. Or a single repo for everyone is the best option?

[handrews]

@Bellangelo We want a unified brand across the different specs, so I think we'll want to stick with spec.openapis.org.

[Bellangelo]

@handrews Fair enough. I see that @darrelmiller invited me to the organization, so now I have access to create a repo. Should I create a spec.openapis.org repo and move there the website?

[handrews]

@Bellangelo I was surprised about repository creation privileges but it looks like a recent change that GitHub made, giving members more abilities. Let's make sure @darrelmiller or another admin is OK with the separate-repository choice.

There might need to be a bit of work to figure out how the publishing of specs and schemas changes. Not so much the technical logistics (which I'm sure you can sort out) but the policy side of things.

[lornajane]

We are generally in favour. But we will need some process, governance and maintenance setup to enable this change. A good discussion in TDC, but we are not ready to make the change immediately.