migrate.sh: the seed tag on the default branch triggers tag CI and changes git describe #83

migrate.sh step 2 creates the pages-default-seed release with gh release create "$SEED_TAG" ... --latest=false (scripts/migrate.sh:237) and no --target, so GitHub creates the tag on the default branch's HEAD. That tag then lives in the default branch's history until step 4 deletes it, which is after the pipeline PR merges. Two things go wrong in the meantime, both seen on DiamondLightSource/python-copier-template during its migration (PR DiamondLightSource/python-copier-template#373):

1. The tag push runs the old CI. Repos whose CI triggers on tags: ['*'] (every python-copier-template project) run their pre-migration docs workflow for pages-default-seed, which publishes /pages-default-seed/ to gh-pages and adds it to the live switcher.json as a version.
2. git describe --tags returns pages-default-seed. Anything that derives a version from the nearest tag picks it up. setuptools-scm is unaffected (it only matches tags that look like versions), but copier writes git describe into _commit, so python-copier-template's own tests now render a CONTRIBUTING link to .../python-copier-template/pages/how-to.html (a 404) and its update test hits a merge conflict. Its CI stays red from step 2 until step 4, and step 4 can't run until the pipeline PR has merged and main has built its own docs.

Proposal

Create the seed tag on a commit outside the default branch's history, e.g. --target "$PAGES_REF" (the gh-pages branch the seed is captured from):

• git describe on the default branch never sees it.
• A tag push on a gh-pages commit finds no workflow files in that tree, so no CI runs.
• The seed is only a release asset read by the publish engine, so nothing should depend on where its tag points. I haven't checked this against publish-gh-pages.yml's release lookup.

This is code-read only, not tested on a fork. It may also be worth a line in the migrate how-to warning that, until then, a repo with tags: ['*'] CI should expect the stray version and a describe-based tool may break between steps 2 and 4.

AI Disclaimer

The code and this description were generated with AI and reviewed/tweaked by the author.