docfx: sync from repo-template (gh-pages bootstrap fix)#95
Merged
Conversation
Sync .github/workflows/docfx.yaml from canonical repo-template to pick up the bootstrap fix from Chris-Wolfgang/repo-template#337. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Syncs the DocFX GitHub Actions workflow with the repo template to fix first-time gh-pages deployments and improve the deployment flow.
Changes:
- Bootstraps a new
gh-pagesbranch by initializing a git repo in$WORK_DIRand adding an authenticatedoriginremote. - Adds a
gh-pagesroot stale-file cleanup step (preservingversions/,CNAME,.nojekyll) before deploying latest docs. - Updates tag ordering logic to use a custom full SemVer precedence comparison (including prerelease identifiers).
Comment on lines
+173
to
+174
| if ($i -ge $aIds.Length) { return -1 } # a has fewer identifiers -> lower precedence | ||
| if ($i -ge $bIds.Length) { return 1 } # b has fewer identifiers -> lower precedence |
Comment on lines
+179
to
+184
| $aIsNum = [int]::TryParse($aId, [ref]([int]$null)) | ||
| $bIsNum = [int]::TryParse($bId, [ref]([int]$null)) | ||
|
|
||
| if ($aIsNum -and $bIsNum) { | ||
| $aVal = [int]$aId | ||
| $bVal = [int]$bId |
Comment on lines
+139
to
+140
| # Sort descending by full SemVer precedence (Major, Minor, Patch, Stable, PreRelease) | ||
| # Convert to a mutable list so we can use a custom comparison for proper SemVer prerelease ordering. |
Comment on lines
+224
to
+234
| # Before deploying the latest docs to the site root, remove any pre-existing | ||
| # root-level files and folders from the gh-pages branch (except the versions/ | ||
| # directory, CNAME, and .nojekyll) so that stale DocFX assets from a previous | ||
| # build do not linger on the live site. | ||
| # The versions/ folder is preserved so that all versioned docs remain accessible | ||
| # while the root is refreshed with the new build. | ||
| if: inputs.deploy_to_pages != false && inputs.deploy_as_latest != false | ||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
| shell: pwsh | ||
| run: | |
Comment on lines
+223
to
+282
| - name: Clean up stale root files from gh-pages | ||
| # Before deploying the latest docs to the site root, remove any pre-existing | ||
| # root-level files and folders from the gh-pages branch (except the versions/ | ||
| # directory, CNAME, and .nojekyll) so that stale DocFX assets from a previous | ||
| # build do not linger on the live site. | ||
| # The versions/ folder is preserved so that all versioned docs remain accessible | ||
| # while the root is refreshed with the new build. | ||
| if: inputs.deploy_to_pages != false && inputs.deploy_as_latest != false | ||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
| shell: pwsh | ||
| run: | | ||
| $branchExists = git ls-remote --heads origin gh-pages | ||
| if (-not $branchExists) { | ||
| Write-Host "ℹ️ gh-pages branch does not exist yet – skipping stale-file cleanup." | ||
| exit 0 | ||
| } | ||
|
|
||
| git config --global user.email "github-actions[bot]@users.noreply.github.com" | ||
| git config --global user.name "github-actions[bot]" | ||
| git remote set-url origin "https://x-access-token:$($env:GITHUB_TOKEN)@github.com/$($env:GITHUB_REPOSITORY).git" | ||
|
|
||
| git fetch origin gh-pages | ||
| # Create a local tracking branch only if it does not already exist | ||
| git show-ref --verify --quiet refs/heads/gh-pages | ||
| if ($LASTEXITCODE -ne 0) { | ||
| git branch gh-pages origin/gh-pages | ||
| } | ||
|
|
||
| $WORK_DIR = Join-Path $env:RUNNER_TEMP 'gh-pages-clean' | ||
| # Remove a leftover worktree from a previous failed run, if any | ||
| git worktree remove "$WORK_DIR" --force 2>&1 | Out-Null | ||
| if (Test-Path $WORK_DIR) { Remove-Item $WORK_DIR -Recurse -Force } | ||
| git worktree add "$WORK_DIR" gh-pages | ||
|
|
||
| # Remove all root-level items EXCEPT: | ||
| # .git – Git metadata (worktree pointer file) | ||
| # CNAME – Custom domain config (if present) | ||
| # .nojekyll – Tells GitHub Pages not to run Jekyll | ||
| # versions/ – All versioned docs (v1.0.0/, latest/, etc.) | ||
| Get-ChildItem -Path $WORK_DIR -Force | Where-Object { | ||
| $_.Name -ne '.git' -and | ||
| $_.Name -ne 'CNAME' -and | ||
| $_.Name -ne '.nojekyll' -and | ||
| $_.Name -ne 'versions' | ||
| } | Remove-Item -Recurse -Force | ||
|
|
||
| git -C "$WORK_DIR" add -A | ||
| git -C "$WORK_DIR" diff --cached --quiet | ||
| if ($LASTEXITCODE -ne 0) { | ||
| git -C "$WORK_DIR" commit ` | ||
| -m "chore: clean up stale root DocFX assets before redeploy [skip ci]" | ||
| git -C "$WORK_DIR" push origin HEAD:gh-pages | ||
| Write-Host "✅ Stale root files removed from gh-pages." | ||
| } else { | ||
| Write-Host "ℹ️ No stale files found in gh-pages root – nothing to clean." | ||
| } | ||
|
|
||
| git worktree remove "$WORK_DIR" --force | ||
|
|
Comment on lines
+351
to
+352
| git -C $WORK_DIR init --initial-branch=gh-pages | ||
| git -C $WORK_DIR remote add origin "https://x-access-token:$($env:GITHUB_TOKEN)@github.com/$($env:GITHUB_REPOSITORY).git" |
Chris-Wolfgang
pushed a commit
that referenced
this pull request
May 9, 2026
…ng order) Mirrors repo-template#341 — same fix into IEnumerable-Extensions's docfx.yaml. The SemVer prerelease comparator's 'fewer prerelease ids' branches were returning the wrong sign for the descending sort. Per SemVer §11.4.4, fewer prerelease ids = lower precedence (1.0.0-alpha < 1.0.0-alpha.1). For descending order (newest first), the lower-precedence value sorts AFTER the higher-precedence one, so 'a has fewer ids' must return positive (place 'a' second). Caught by Copilot review on PR #95. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Sync
.github/workflows/docfx.yamlfromrepo-templateto pick up the gh-pages bootstrap fix from Chris-Wolfgang/repo-template#337.What changed
The "Deploy docs to GitHub Pages" step had a latent bug: when the
gh-pagesbranch did not yet exist on the remote,$WORK_DIRwas created as a plain directory and the subsequentgit add/diff --cached/commit/pushfailed withfatal: not a git repository. The fix initializes the directory as a git repo ongh-pagesand adds the authenticatedoriginremote, so the existing add/commit/push works on a first-ever deploy. Cleanup also branches betweengit worktree remove(worktree path) andRemove-Item(fresh-repo path).If
gh-pagesalready exists in this repo (the common case), this change is a no-op at runtime — the bootstrap branch is only taken on a fresh repo.Test plan
gh-pagesis unaffected