docs: add latest documentation alias (#1243)

Author: kabir

.agents/skills/release-a2a/SKILL.md

@@ -159,6 +159,8 @@ When applicable:
 
 4. For Final releases: set the previous default version's `defaultVersion` to `false`.
 
+   The documentation deployment automatically exposes the version marked `defaultVersion: true` under `/latest/`, including Javadoc. Do not create or update a `docs/content/latest` directory during a release.
+
 5. For pre-releases superseding a prior pre-release in the same X.Y.Z series: remove the old pre-release's content folder (`docs/content/<old-version_underscored>`), version yml (`docs/data/versions/<old-version>.yml`), and apidocs folder (`docs/public/<old-version_underscored>/apidocs/`).
 
 6. Generate Javadoc. The `site-javadoc` profile outputs to `docs/public/dev/apidocs/`:

.github/scripts/create-latest-alias.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+versions_dir=${1:?Usage: create-latest-alias.sh <versions-dir> <site-dir>}
+site_dir=${2:?Usage: create-latest-alias.sh <versions-dir> <site-dir>}
+latest_path=""
+
+for version_file in "$versions_dir"/*.yml; do
+    candidate=$(awk '
+        $1 == "path:" {
+            path = $2
+            gsub(/^"|"$/, "", path)
+        }
+        $1 == "defaultVersion:" && $2 == "true" {
+            default_version = 1
+        }
+        END {
+            if (default_version && path != "") {
+                print path
+            }
+        }
+    ' "$version_file")
+
+    if [[ -n "$candidate" ]]; then
+        if [[ -n "$latest_path" ]]; then
+            echo "Expected exactly one default documentation version" >&2
+            exit 1
+        fi
+        latest_path="$candidate"
+    fi
+done
+
+if [[ -z "$latest_path" ]]; then
+    echo "No default documentation version found" >&2
+    exit 1
+fi
+
+if [[ ! -d "$site_dir/$latest_path" ]]; then
+    echo "Default documentation version is not present in the generated site: $latest_path" >&2
+    exit 1
+fi
+
+if [[ -e "$site_dir/latest" || -L "$site_dir/latest" ]]; then
+    echo "Generated site already contains a latest alias" >&2
+    exit 1
+fi
+
+ln -s "$latest_path" "$site_dir/latest"

.github/scripts/test-create-latest-alias.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+work_dir=$(mktemp -d)
+trap 'rm -rf "$work_dir"' EXIT
+
+versions_dir="$work_dir/versions"
+site_dir="$work_dir/site"
+mkdir -p "$versions_dir" "$site_dir/1_4_0_Final/apidocs" "$site_dir/1_5_0_Final/apidocs"
+
+cat > "$versions_dir/1.4.0.Final.yml" <<'EOF'
+path: "1_4_0_Final"
+defaultVersion: false
+EOF
+
+cat > "$versions_dir/1.5.0.Final.yml" <<'EOF'
+path: "1_5_0_Final"
+defaultVersion: true
+EOF
+
+"$script_dir/create-latest-alias.sh" "$versions_dir" "$site_dir"
+
+test -L "$site_dir/latest"
+test "$(readlink "$site_dir/latest")" = "1_5_0_Final"
+test -d "$site_dir/latest/apidocs"

.github/workflows/check-site.yml

@@ -10,8 +10,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - name: Test latest documentation alias
+        run: .github/scripts/test-create-latest-alias.sh
       - name: Generate Roq Site
         uses: quarkiverse/quarkus-roq@d0bdb4255f4dcc3ddd218c83f9dd19faa823ac31 # v1.1
         with:
           site-directory: ./docs/
           github-pages: 'false'
+      - name: Verify latest documentation alias
+        run: |
+          .github/scripts/create-latest-alias.sh docs/data/versions docs/target/roq
+          test -f docs/target/roq/latest/apidocs/index.html

.github/workflows/deploy-site.yml

@@ -10,13 +10,26 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read    # to check out the site sources
+      pages: write      # to upload the GitHub Pages artifact
+      id-token: write   # to verify the deployment originates from an appropriate source
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       - name: Generate Roq Site
         uses: quarkiverse/quarkus-roq@d0bdb4255f4dcc3ddd218c83f9dd19faa823ac31 # v1.1
         with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}   # Used to automatically get the GitHub Pages url
           site-directory: ./docs/
+          github-pages: 'false'
+          site-url: https://a2aproject.github.io/a2a-java
+      - name: Create latest documentation alias
+        run: .github/scripts/create-latest-alias.sh docs/data/versions docs/target/roq
+      - name: Setup Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
+        with:
+          path: docs/target/roq
   deploy:
     environment:
       name: github-pages

README.md

@@ -19,7 +19,7 @@ Full documentation is available at **[a2aproject.github.io/a2a-java](https://a2a
 
 - [Server Guide](https://a2aproject.github.io/a2a-java/server) — Run your agentic Java application as an A2A server
 - [Client Guide](https://a2aproject.github.io/a2a-java/client) — Communicate with any A2A-compliant agent
-- [Javadoc](https://a2aproject.github.io/a2a-java/1_3_0_Final/apidocs/) — Java API reference
+- [Javadoc](https://a2aproject.github.io/a2a-java/latest/apidocs/) — Java API reference
 - [Community Articles](https://a2aproject.github.io/a2a-java/community) — Tutorials, blog posts, and videos
 - [Announcements](https://a2aproject.github.io/a2a-java/announces) — Release announcements and project news
 - [Contributing](https://a2aproject.github.io/a2a-java/contributing) — Developer guide for contributing

RELEASE.md

@@ -184,6 +184,8 @@ Edit `docs/data/versions/X.Y.Z.Final.yml`:
 Update the previous default version's data file (e.g., `docs/data/versions/<previous-version>.yml`):
 - Set `defaultVersion` to `false`
 
+The documentation deployment automatically exposes the version marked `defaultVersion: true` under `/latest/`, including Javadoc. Do not create or update a `docs/content/latest` directory during a release.
+
 Review the new version's content for accuracy — ensure all pages reflect features available in this release.
 
 #### Generate Javadoc (major/minor releases only)