Procedure: Deploy and clean up gh-pages branch

Follow these steps after PR #499 is merged to complete the migration to native GitHub Pages deployment.

Pre-requisites

• PR Migrate to native GitHub Pages deployment (no gh-pages branch) #499 merged to main

Step 1: Change GitHub Pages source

1. Go to Settings → Pages in the repository
2. Under "Build and deployment", change Source from "Deploy from a branch" to "GitHub Actions"
3. Save

Step 2: Trigger a test deployment

Create a publish tag to trigger the updated workflow:

git checkout main
git pull origin main
git tag publish-2026mar26-test
git push origin publish-2026mar26-test

Step 3: Verify deployment

• Check the Actions tab — the publish workflow should complete successfully
• Verify the github-pages environment shows the deployment in the repo's Environments page
• Visit https://python-programming.quantecon.org/ and confirm the site loads correctly
• Spot-check 3+ lecture pages to verify content renders properly
• Verify release assets (tar.gz, checksum, manifest) are attached to the release
• Verify the notebook sync step completed (check lecture-python-programming.notebooks repo)

Step 4: Verify linkcheck still works

Either wait for the weekly scheduled run, or trigger manually:

1. Go to Actions → Link Checker [Anaconda, Linux]
2. Click Run workflow (workflow_dispatch)
3. Verify it completes and correctly downloads/extracts the Pages artifact

Step 5: Delete the gh-pages branch

Once everything above is confirmed working:

# Delete remote gh-pages branch
git push origin --delete gh-pages

# Delete local gh-pages branch (if it exists)
git branch -D gh-pages 2>/dev/null || true

# Clean up local references
git remote prune origin

Expected space savings: ~300MB reclaimed from the repository (153 deploy snapshot commits from Oct 2020 – March 2026).

Note: Team members who have cloned the repo should run:

git fetch --prune
git branch -D gh-pages 2>/dev/null || true
git gc --prune=now

Rollback procedure

If the native deployment fails and the site goes down:

1. Re-create the gh-pages branch from the last known good deploy:

   git checkout fc6487c  # latest gh-pages commit (March 20, 2026 deploy)
   git checkout -b gh-pages
   git push origin gh-pages

2. Change Settings → Pages source back to "Deploy from a branch" (gh-pages / root)
3. Revert PR Migrate to native GitHub Pages deployment (no gh-pages branch) #499 on main