diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 8fadf4d..33b85fc 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -4,7 +4,7 @@ on: workflow_call: inputs: rc_ref: - description: Git ref containing the release-candidate documentation + description: Git ref containing the documentation to publish under /rc required: true type: string @@ -33,11 +33,26 @@ jobs: fetch-depth: 0 fetch-tags: true - - name: Find latest release tag + - name: Find latest release tag with documentation id: stable working-directory: rc-source run: | - stable_tag=$(git tag --list | awk '/^[0-9]+\.[0-9]+\.[0-9]+$/ { print }' | sort -V | tail -n 1) + stable_tag=$( + git tag --list | + awk '/^[0-9]+\.[0-9]+\.[0-9]+$/ { print }' | + sort -Vr | + while IFS= read -r tag; do + if git cat-file -e "${tag}:mkdocs.yml" 2>/dev/null; then + printf '%s\n' "$tag" + break + fi + done + ) + if [[ -n "$stable_tag" ]]; then + echo "Using stable documentation from $stable_tag" + else + echo "No stable release tag contains mkdocs.yml; using the RC source for initial stable documentation" + fi echo "stable_tag=$stable_tag" >> "$GITHUB_OUTPUT" - uses: actions/checkout@v7 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a54545c..a5242fe 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -205,7 +205,7 @@ jobs: id-token: write uses: ./.github/workflows/publish-docs.yml with: - rc_ref: main + rc_ref: ${{ github.sha }} build-release-installer: runs-on: windows-latest diff --git a/docs/maintainers.md b/docs/maintainers.md index 1bfad00..5a3cd19 100644 --- a/docs/maintainers.md +++ b/docs/maintainers.md @@ -21,7 +21,7 @@ Zensical reads the existing MkDocs-compatible `mkdocs.yml`, so the project does ## Publishing -The Pages artifact contains the latest tagged release at the site root and documentation from `main` under `/rc/`. Release tags update the stable site; pushes to `main` update the RC site. Both trees are rebuilt for each deployment because GitHub Pages deploys the complete artifact rather than merging individual paths. +The Pages artifact contains documentation from the latest stable tag that includes `mkdocs.yml` at the site root and documentation from the triggering commit under `/rc/`. RC builds use the `main` commit that triggered the build; release builds use the tagged release commit. Until a stable release includes the documentation, the root site is built from the triggering commit as an initial stable snapshot. Both trees are rebuilt for each deployment because GitHub Pages deploys the complete artifact rather than merging individual paths. The release workflow publishes after the release ZIP has been created, and the RC workflow publishes after a push to `main`. Both use GitHub Pages artifacts; the source Markdown remains in `docs/`.