Figure out how to safely 😅 squash commits

[jni]

🧰 Task

Opening this as a reminder to try to do what #658 disastrously attempted to do, while also writing a post-mortem about what I thought it was doing.

Before seeing the effects of #658, my mental model of what the deploy action was doing was:

• clone the gh-pages branch from https://github.com/napari/napari.github.io
• build the docs and place the build output in the specified folder (dev for main, x.y.z for a tag)
• git add that folder
• commit
• push changes back to the gh-pages branch

What I thought force-orphan would do is to add a single step (and force push):

• clone the gh-pages branch from https://github.com/napari/napari.github.io
• build the docs and place the build output in the specified folder (dev for main, x.y.z for a tag)
• git add that folder
• commit
• squash the complete history of gh-pages
• force push changes back to the gh-pages branch

What instead happened seems to be:

• git init
• build the docs and place the build output in the specified folder
• git add that folder
• commit
• force push to the gh-pages branch

The second model is still something we want to achieve, so we should investigate how to make it happen.

And we should fork the repo before trying it out this time... 😅

[jni]

I serendipitously found the single-commit option in jamesives/github-pages-deploy-action

single-commit

This option can be toggled to true if you'd prefer to have a single commit on the deployment branch instead of maintaining the full history. Using this option will also cause any existing history to be wiped from the deployment branch.

That's the right incantation, but we use peaceiris/actions-gh-pages instead of jamesives. We'd have to check whether we can switch over, or use jamesives in a different part of the workflow.