Should we-organize our GitHub pages to a separate repo (by way of a directory on main)?

[handrews]

trafficstars

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 https://github.com/OAI/OpenAPI-Specification/issues/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.

[lornajane]

Discussed in TSC and agreed that a new repository will be a good home for our web presence and having it separate will give us a few advantages:

• people who care about web tooling can help us with it without needing access to any/all of the spec repos
• it's really clear that changes there are being published to our official site (currently you can merge something to a branch and it's not at all obvious it will cause a rebuild/deploy elsewhere)
• we may be able to get better previews for pull requests with the separate repository setup

@Bellangelo does it make sense to proceed with #3868 to apply the changes you already worked on since I assume we'll use the main branch in a new repo too? Let us know what you think.

[handrews]

@Bellangelo @frankkilcommins I think when moving to a separate repository, we should endeavor to move as much infrastructure as possible out of this repository. As obnoxious as git submodules are, if we need to run build steps from this or other specification repositories, I think it would be better to pull in the common repo as a submodule rather than have any duplicated build infrastructure.

[Bellangelo]

@Bellangelo does it make sense to proceed with https://github.com/OAI/OpenAPI-Specification/pull/3868 to apply the changes you already worked on since I assume we'll use the main branch in a new repo too? Let us know what you think.

@lornajane Hmm.. that's a good question. Since we want to immediately move to a new repo we might not need to proceed with the https://github.com/OAI/OpenAPI-Specification/pull/3868 as it will require double the work from the Arazzo team since they will have to create a PR for this change and a second one for when we will move to the new repo. But what is missing from our side is the mechanism that they have implemented in Arazzo that builds the site and opens a new PR in the repo. If we think that this whole progress will take too much time we might want to proceed with https://github.com/OAI/OpenAPI-Specification/pull/3868 just so we can get things moving. To sum up, I am ok to proceed with both ways. If we go immediately with the new repo I will need someone to create a new repo for me.

I think it would be better to pull in the common repo as a submodule rather than have any duplicated build infrastructure.

@handrews Yes and no. While I agree that we should minimize our infrastructure, the truth is that it is just a coincidence that these 2 specs both use the same building mechanism. I am 100% sure that Arazzo copied our mechanism for a faster release. Other than this, I think there isn't any rule / constraint / limitation for Arazzo to choose whatever site builder it wants. Perhaps, I might have lost your point and actually what you are suggesting is that they should be handled as a single site instead.

[handrews]

I am 100% sure that Arazzo copied our mechanism for a faster release. Other than this, I think there isn't any rule / constraint / limitation for Arazzo to choose whatever site builder it wants.

We in general want to get everything on the same infrastructure. This is really one big project, and we should be releasing all of our specifications the same and managing our web sites the same (although I realize that might not be immeidately apparent... it's aspirational 🙂 )

---

Info from PR #3868, which we are closing simply because the whole structure has changed too much and the PR will need to be re-visited:

---

What [@Bellangelo did]:

1. Go to gh-pages and move all files under the docs folder which Github supports.
2. Go to main branch and run git merge gh-pages --allow-unrelated-histories. This merged the 2 branches even if they had unrelated histories.
3. Updated scripts and references. There are some references in the spec.js files but I think they are unused.

What we need to do after merge:

1. Go to Settings>Pages and under the Branch section select the main branch and the docs folder`.
2. After you update the settings, an action will run to deploy the site again.
3. We keep the gh-pages for a few weeks, just to be able to quickly change in case of a bug in the process, and then we delete it.

How to review To quickly skip and verify the updated files, just follow the What I have done section and then you can just git diff to distinguished what files have been moved and what files contain actual changes.