From 9d05864c19b48ecd6ff9410decd8446d2825ed3a Mon Sep 17 00:00:00 2001 From: Matthew Mellor Date: Wed, 4 Mar 2026 19:24:47 -0600 Subject: [PATCH] docs(container): add auto-generated tool versions page Add /docs/container/versions/ page showing tool versions per release. A scheduled GitHub Actions workflow fetches tool-versions.json from dev-toolchain releases and regenerates the page daily. Co-Authored-By: Claude Opus 4.6 --- .github/scripts/generate-versions-page.sh | 105 +++++++++++++++++++++ .github/workflows/update-tool-versions.yml | 42 +++++++++ content/docs/container/_index.md | 5 + content/docs/container/versions.md | 16 ++++ 4 files changed, 168 insertions(+) create mode 100755 .github/scripts/generate-versions-page.sh create mode 100644 .github/workflows/update-tool-versions.yml create mode 100644 content/docs/container/versions.md diff --git a/.github/scripts/generate-versions-page.sh b/.github/scripts/generate-versions-page.sh new file mode 100755 index 0000000..25b4dd7 --- /dev/null +++ b/.github/scripts/generate-versions-page.sh @@ -0,0 +1,105 @@ +#!/usr/bin/env bash +# .github/scripts/generate-versions-page.sh +# +# Generates the Tool Versions documentation page for devrail.dev. +# Fetches tool-versions.json release assets from the dev-toolchain repo +# and outputs a complete Hugo markdown page to stdout. +# +# Usage: bash .github/scripts/generate-versions-page.sh +# Requires: gh (GitHub CLI), jq, curl +# Environment: GH_TOKEN must be set (provided by GitHub Actions) + +set -euo pipefail + +REPO="devrail-dev/dev-toolchain" + +# --- Helpers --- + +render_table() { + local json="$1" + echo "| Tool | Version |" + echo "|---|---|" + echo "${json}" | jq -r '.tools | to_entries | sort_by(.key) | .[] | "| \(.key) | \(.value) |"' +} + +# --- Frontmatter and intro --- + +cat <<'FRONTMATTER' +--- +title: "Tool Versions" +linkTitle: "Tool Versions" +weight: 10 +description: "Tool versions included in each dev-toolchain container release." +--- + + + + +This page shows the exact tool versions shipped in each release of the +[dev-toolchain container](/docs/container/). It is updated automatically +when new releases are published. + +FRONTMATTER + +# --- Fetch releases --- +# gh api returns newest first by default. Select non-draft releases and +# extract tag, date, and the tool-versions.json asset download URL. + +releases=$(gh api "repos/${REPO}/releases" --paginate --jq ' + .[] | select(.draft == false) | + { + tag: .tag_name, + date: (.published_at | split("T")[0]), + asset_url: ( + [.assets[] | select(.name == "tool-versions.json") | .url] | first // null + ) + } +') + +# --- Render page --- + +first=true +has_previous=false + +while IFS= read -r release; do + tag=$(echo "${release}" | jq -r '.tag') + date=$(echo "${release}" | jq -r '.date') + asset_url=$(echo "${release}" | jq -r '.asset_url') + + # Skip releases without a tool-versions.json asset + if [[ "${asset_url}" == "null" ]]; then + continue + fi + + # Download the asset via the GitHub API (works for public and private repos) + versions_json=$(gh api "${asset_url}" --jq '.' 2>/dev/null) || continue + + if ${first}; then + echo "## Latest Release: ${tag}" + echo "" + echo "Released ${date}." + echo "" + render_table "${versions_json}" + echo "" + first=false + else + if ! ${has_previous}; then + echo "## Previous Releases" + echo "" + has_previous=true + fi + echo "
" + echo "${tag} (${date})" + echo "" + render_table "${versions_json}" + echo "" + echo "
" + echo "" + fi +done <<< "${releases}" + +# Fallback if no releases have the asset yet +if ${first}; then + echo "No releases with tool version manifests are available yet." + echo "Version data will appear here after the next dev-toolchain release." +fi diff --git a/.github/workflows/update-tool-versions.yml b/.github/workflows/update-tool-versions.yml new file mode 100644 index 0000000..c2e0fc6 --- /dev/null +++ b/.github/workflows/update-tool-versions.yml @@ -0,0 +1,42 @@ +name: Update Tool Versions Page + +on: + schedule: + # Daily at 7:00 AM UTC (1h after Monday dev-toolchain builds) + - cron: '0 7 * * *' + workflow_dispatch: {} + +permissions: + contents: write + +jobs: + update-versions: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Generate tool versions page + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + bash .github/scripts/generate-versions-page.sh \ + > content/docs/container/versions.md + + - name: Check for changes + id: diff + run: | + if git diff --quiet content/docs/container/versions.md; then + echo "changed=false" >> "$GITHUB_OUTPUT" + else + echo "changed=true" >> "$GITHUB_OUTPUT" + fi + + - name: Commit and push + if: steps.diff.outputs.changed == 'true' + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git add content/docs/container/versions.md + git commit -m "docs(container): update tool versions page" + git push diff --git a/content/docs/container/_index.md b/content/docs/container/_index.md index 80031f7..87dfebf 100644 --- a/content/docs/container/_index.md +++ b/content/docs/container/_index.md @@ -184,6 +184,11 @@ The dev-toolchain container includes all tools needed for every supported langua | git-cliff | Changelog generation from conventional commits | | pre-commit | Git hook management | +## Tool Version History + +For the exact versions of every tool in each container release, see +[Tool Versions](/docs/container/versions/). + ## Running Tools Directly While the Makefile delegation pattern is the recommended approach, you can invoke the container directly for debugging or exploration: diff --git a/content/docs/container/versions.md b/content/docs/container/versions.md new file mode 100644 index 0000000..1155c81 --- /dev/null +++ b/content/docs/container/versions.md @@ -0,0 +1,16 @@ +--- +title: "Tool Versions" +linkTitle: "Tool Versions" +weight: 10 +description: "Tool versions included in each dev-toolchain container release." +--- + + + + +This page shows the exact tool versions shipped in each release of the +[dev-toolchain container](/docs/container/). It is updated automatically +when new releases are published. + +No releases with tool version manifests are available yet. Version data +will appear here after the next dev-toolchain release.