diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 939ae096a7f..20cd2cdd547 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -125,10 +125,21 @@ jobs: fi exit $err + - name: Resolve Python version + id: pyver + run: | + # Read the version from the checked-out branch (ref input) so each + # version builds with its own Python; fall back to 3.13 if absent. + if [ -f .python-version ]; then + echo "version=$(tr -d '[:space:]' < .python-version)" >> "$GITHUB_OUTPUT" + else + echo "version=3.13" >> "$GITHUB_OUTPUT" + fi + - name: Set up Python uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 with: - python-version: "3.13" + python-version: ${{ steps.pyver.outputs.version }} cache: "pip" - name: Install pip dependencies @@ -176,10 +187,19 @@ jobs: with: ref: ${{ inputs.ref }} + - name: Resolve Python version + id: pyver + run: | + if [ -f .python-version ]; then + echo "version=$(tr -d '[:space:]' < .python-version)" >> "$GITHUB_OUTPUT" + else + echo "version=3.13" >> "$GITHUB_OUTPUT" + fi + - name: Set up Python uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 with: - python-version: "3.13" + python-version: ${{ steps.pyver.outputs.version }} cache: "pip" - name: Install pip dependencies @@ -188,6 +208,11 @@ jobs: - name: Build epub documentation run: | set -e + # HTML sets DOCS_DISPLAY_VERSION via detect-versions and PDF via DOCS_RELEASE; + # the epub job needs it too so stable branches render their real version. + if [[ "${{ inputs.branch }}" =~ ^stable([0-9]+)$ ]]; then + export DOCS_DISPLAY_VERSION="${BASH_REMATCH[1]}" + fi cd ${{ matrix.manual.directory }} make epub ls -la ${{ matrix.manual.build_epub_path }} @@ -282,10 +307,19 @@ jobs: with: ref: ${{ inputs.ref }} + - name: Resolve Python version + id: pyver + run: | + if [ -f .python-version ]; then + echo "version=$(tr -d '[:space:]' < .python-version)" >> "$GITHUB_OUTPUT" + else + echo "version=3.13" >> "$GITHUB_OUTPUT" + fi + - name: Set up Python uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 with: - python-version: "3.13" + python-version: ${{ steps.pyver.outputs.version }} # pip cache is not compatible with the Docker container # cache: "pip" diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index e50bafda54f..b64cdf9a212 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -15,6 +15,12 @@ on: schedule: - cron: '0 2 * * *' # 02:00 UTC daily workflow_dispatch: + inputs: + branch: + description: "Build & deploy a single branch (e.g. master or stable34). Leave empty to build master + all supported stable branches." + required: false + type: string + default: "" permissions: contents: read @@ -30,15 +36,46 @@ jobs: outputs: branches: ${{ steps.set.outputs.branches }} steps: - - name: Collect master and stable branches + - name: Checkout repository + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + + - name: Setup PHP + uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2 + with: + php-version: '8.3' + + - name: Compute branch matrix id: set env: - GH_TOKEN: ${{ github.token }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + INPUT_BRANCH: ${{ inputs.branch }} run: | - stable_branches=$(gh api "repos/${{ github.repository }}/branches" --paginate \ - --jq '.[].name | select(startswith("stable"))' | sort -Vr) - # Build a JSON array: ["master", "stable34", "stable33", ...] - branches_json=$(printf '%s\n' master ${stable_branches} | jq -R . | jq -cs .) + # Manual single-branch dispatch: build only the requested branch. + if [ -n "${INPUT_BRANCH}" ]; then + branches_json=$(printf '%s' "${INPUT_BRANCH}" | jq -R . | jq -cs .) + echo "Single-branch dispatch: ${branches_json}" + echo "branches=${branches_json}" >> $GITHUB_OUTPUT + exit 0 + fi + + # Scheduled / plain dispatch: master + every stable branch that is still + # within the support window. Ancient branches (e.g. stable10) are on the + # remote but out of support and would blow past the 256-jobs-per-run cap. + nums=$(git ls-remote --heads origin "heads/stable[0-9][0-9]" \ + | sed -n 's?.*refs/heads/stable\([0-9]\{2\}\)$?\1?p' | sort -n) + + # Reuse the shared helper to get the supported range (lowest..highest). + eval $(php build/detect-versions.php ${nums}) + echo "Supported stable range: ${lowest_stable}..${highest_stable}" + + selected="master" + for n in ${nums}; do + if [ "$n" -ge "$lowest_stable" ] && [ "$n" -le "$highest_stable" ]; then + selected="${selected} stable${n}" + fi + done + + branches_json=$(printf '%s\n' ${selected} | jq -R . | jq -cs .) echo "Matrix branches: ${branches_json}" echo "branches=${branches_json}" >> $GITHUB_OUTPUT @@ -109,10 +146,12 @@ jobs: id: apply if: steps.staged.outputs.has_stage == 'true' run: | + deployed="" for d in stage/*/; do [ -d "$d" ] || continue branch="$(basename "$d")" echo "Applying version folder: ${branch}" + deployed="${deployed} ${branch}" mkdir -p "server/${branch}" for artifact in "stage/${branch}"/*; do @@ -132,6 +171,10 @@ jobs: done done + # Record which folders we deployed this run, so later steps only touch + # those (not the ancient version folders already present on gh-pages). + echo "folders=$(echo ${deployed} | xargs)" >> $GITHUB_OUTPUT + # Cleanup empty directories find . -type d -empty -delete @@ -182,17 +225,50 @@ jobs: if: steps.apply.outputs.has_changes == 'true' run: | default_branch="${{ github.event.repository.default_branch }}" - git fetch origin "${default_branch}" + # gh-pages is checked out single-branch, so there is no origin/ + # tracking ref. Fetch with an explicit refspec to create it. + git fetch origin "${default_branch}:refs/remotes/origin/${default_branch}" git checkout "origin/${default_branch}" -- go.php/index.html user_manual/index.html - for d in server/*/; do - [ -d "$d" ] || continue - branch="$(basename "$d")" + # Only the folders deployed this run — not every historical version + # already on gh-pages (some old ones have an incompatible layout). + for branch in ${{ steps.apply.outputs.folders }}; do + rm -rf "server/${branch}/go.php" mkdir -p "server/${branch}/go.php" "server/${branch}/user_manual" cp go.php/index.html "server/${branch}/go.php/index.html" cp user_manual/index.html "server/${branch}/user_manual/index.html" done + # ======================================================================== + # COMPOSE PR BODY — per-version change counts + # ======================================================================== + - name: Compose PR body + id: body + if: steps.apply.outputs.has_changes == 'true' + run: | + # Stage everything so new files count too (create-pull-request commits this). + git add -A + { + echo "text<> "$GITHUB_OUTPUT" + - name: Create Pull Request for documentation deployment uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1 id: cpr @@ -206,9 +282,7 @@ jobs: branch: "automated/deploy/documentation" base: gh-pages title: "Documentation update" - body: | - This PR was automatically generated by the scheduled deploy workflow - and includes the latest documentation for all built versions. + body: ${{ steps.body.outputs.text }} delete-branch: true labels: "automated, 3. to review" diff --git a/.python-version b/.python-version new file mode 100644 index 00000000000..24ee5b1be99 --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.13