Procedure: Migrate to native Pages deployment and delete gh-pages branch

[mmcky]

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

[mmcky]

Migration complete. All steps verified:

• PR Migrate to native GitHub Pages deployment (no gh-pages branch) #499 merged
• Pages source changed to GitHub Actions
• Test deployment (publish-2026mar26) succeeded
• Site live at https://python-programming.quantecon.org/ (build_type: workflow)
• Release assets (tar.gz, checksum, manifest) attached
• Linkcheck workflow runs successfully against release assets
• gh-pages branch deleted

[mmcky]

Repo size: before vs after gh-pages removal

	Older copy (with gh-pages)	Fresh clone (no gh-pages)	Savings
.git size	358 MB	15 MB	343 MB (96% reduction)
size-pack	356.55 MB	14.58 MB	341.97 MB
objects in pack	15,737	3,579	12,158 fewer

Fresh clone performed on March 26, 2026 after gh-pages branch deletion. GitHub has already garbage-collected the unreferenced objects server-side.