Recommendations on removing versions from a GHA published site

[swcurran]

I'm looking for recommendations on how to remove versions from a Mkdocs site published with GHA. I have two scenarios where I need things deleted -- a one time process because of a mistake in initial deploying the site, and the other -- an ongoing need to remove "release candidate" builds.

GitHub repo: https://github.com/hyperledger/aries-cloudagent-python
Deployed pages: https://hyperledger.github.io/aries-cloudagent-python/
GHA: https://github.com/hyperledger/aries-cloudagent-python/blob/main/.github/workflows/publish-docs.yml

I specifically want to remove the version "docs-v0.12.0rc1" as it was created while I was trying to figure out the best flow for our situation.

We publish "Release Candidates" such as 0.12.0rc1, 0.12.0rc2. As we finalize the release (e.g., when 0.12.0 is released), I'd like to remove the release candidate docs from the published site.

Is there a recommend way to do that? Ideas I've had:

• Edit the gh-pages branch and remove the version folders and the versions from the "versions.yml". But I think that messes think up with the sitemap, and generally seems like a bad approach.
• Add a temporary mike delete <version> call for the specific versions to be deleted, making sure to ignore the error if the version is not there (e.g., it has already been run and deleted).
• Create a manually triggered GHA that takes a parameter of the version to be removed. The GHA would run mike delete <version>.
• Currently we are triggering a version by adding a branch docs-v<version>. Create a GHA that runs on delete and that deletes the version associated with the delete branch.

Suggestions would be welcome!

Thanks!

[jimporter]

For one-off cases, you can just do it all locally via mike delete, and push back upstream.

For clearing RCs in general, why not just write a small script that runs in your CI when you tag the final version? You can use mike list --json to get all the versions in JSON format (this is just your versions.json file on the gh-pages branch), and then loop through them to pick out any versions to be deleted. Then call mike delete <each-version>.

[swcurran]

Good ideas. Thanks for the suggestions — good ones. The first sounds much better than the rm -rf… that I was considering doing. I’ve nicely messed up my local fork with that one :-).

I think the loop idea is a good one. Delete is only called when needed, but can always be part of the script.

Thanks!

[swcurran]

Actually — I’m not quite clear on the logistics of the one-off. Assuming I have a fork, is the process:

• checkout gh-pages
• run mike delete <version>
• PR to the gh-pages branch of the main repo

When I run locally, I don’t touch the gh-pages branch, so wanted to be sure of the process. I still don’t quite understand the magic that mike is doing :-)

Thanks!

[jimporter]

Yeah, that'll work. Think of mike as simply a tool that generates commits for you on the gh-pages branch. There's actually very little magic happening. The actual process is essentially:

1. Read versions.json
2. Build MkDocs to a temporary directory (site/)
3. Update versions as necessary in the data structure
4. Generate a Git commit with the new versions.json and the HTML docs put into the correct subdir(s)

[swcurran]

So my steps were a little different, and I’ll add a caveat. Adding this so others know what the process is and what might be needed.

1. Setup: I have a local clone of a fork of the repo.
2. I was on main branch of my local. Trying to run mike on the gh-pages branch doesn’t work — no mkdocs data...
3. I ran the mike delete <version-to-delete>
4. I switch to the my local gh-pages branch. I used git switch gh-pages, but probably could have just done git checkout gh-pages. Everything looked good — versions.yml was updated, and the offending folder was gone. Yay!
5. Per the notice that I was one commit ahead of the upstream and what to do about it, I did a git push and the repo I forked from was updated. Again — yay!

The caveat for me was that I was pushing to a Linux Foundation open source repo, and all commits MUST have [DCO - Developer Certificate of Origin](https://github.com/apps/dco signoff) (“-s” on a git commit), the commit from the delete DID not have that. And since the gh-pages branch had no branch protection, it allowed the “unsigned” commit. I had to do some clean up (git —amend -s, git push --force-with-lease to get the proper signoff done). I think I could have done a mike delete version-to-delete -m “<proper text for a sign-off>” and all would have been well from the start.

So all good now, with a bit of an adventure along the way...