merge queue: checking unstable (581bde1) and #1210 together

.github/workflows/docs.yml

@@ -1,17 +1,19 @@
 name: docs
 
 on:
-  push:
-    branches:
-      - unstable
+  release:
+    types: [published]
+  workflow_dispatch:
 
+# All runs deploy to the same S3 bucket with --delete, so they must serialize,
+# and an in-flight sync must never be cancelled halfway through.
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  group: docs-deploy
+  cancel-in-progress: false
 
 jobs:
   build-and-upload-to-s3:
-    if: github.repository_owner == 'sigp'
+    if: github.repository_owner == 'sigp' && !github.event.release.prerelease
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v6
@@ -23,17 +25,23 @@ jobs:
           cache: 'npm'
           cache-dependency-path: docs/package-lock.json
 
+      # Step timeouts on the network-bound steps keep a hang from holding the
+      # docs-deploy concurrency group (default job timeout is 6h). Deliberately
+      # no job-level timeout: it could cancel the S3 sync mid-run.
       - name: Install dependencies
         run: npm ci
         working-directory: docs
+        timeout-minutes: 10
 
       - name: Install Playwright browsers
         run: npx playwright install
         working-directory: docs
+        timeout-minutes: 10
 
       - name: Sync version and GitHub stars
         run: npm run sync-version
         working-directory: docs
+        timeout-minutes: 10
 
       - name: Build vocs
         run: npm run build

docs/README.md

@@ -65,6 +65,14 @@ To preview the built site:
 npm run preview
 ```
 
+## Deployment
+
+The live site ([anchor.sigmaprime.io](https://anchor.sigmaprime.io)) is deployed by the
+`docs` GitHub workflow when a release is published, so the published docs always match the
+latest released binary. Docs merged to `unstable` do not go live until the next release.
+For an out-of-band redeploy (e.g. a docs fix cherry-picked to `stable`), run the workflow
+manually: `gh workflow run docs.yml --ref stable`.
+
 ## Contributing
 
 ### Adding New Pages

docs/docs/pages/installation.mdx

@@ -35,8 +35,8 @@ wget https://github.com/sigp/anchor/releases/download/<version>/anchor-<version>
 tar -xvf anchor-<version>-<platform>.tar.gz
 
 # Specific version example
-wget https://github.com/sigp/anchor/releases/download/v1.1.0/anchor-v1.1.0-unknown-linux-gnu.tar.gz
-tar -xvf anchor-v1.1.0-unknown-linux-gnu.tar.gz
+wget https://github.com/sigp/anchor/releases/download/v1.1.0/anchor-v1.1.0-x86_64-unknown-linux-gnu.tar.gz
+tar -xvf anchor-v1.1.0-x86_64-unknown-linux-gnu.tar.gz
 sudo mv anchor /usr/local/bin/
 ```
 

docs/sync-version.js

@@ -87,15 +87,17 @@ async function updateVersionAndStatsInFiles(version, stats) {
   const installationPath = join(__dirname, 'docs/pages/installation.mdx');
   let installationContent = readFileSync(installationPath, 'utf8');
 
-  // Replace download URL versions
+  // Replace download URL versions. The filename version pattern must not have an
+  // optional -suffix group: it would greedily swallow the architecture component
+  // (anchor-v1.1.0-x86_64-... -> anchor-v1.2.0-...).
   installationContent = installationContent.replace(
-    /wget https:\/\/github\.com\/sigp\/anchor\/releases\/download\/v[\d.]+(?:-[\w.]+)?\/anchor-v[\d.]+(?:-[\w.]+)?-/g,
+    /wget https:\/\/github\.com\/sigp\/anchor\/releases\/download\/v[\d.]+(?:-[\w.]+)?\/anchor-v[\d.]+-/g,
     `wget https://github.com/sigp/anchor/releases/download/${vVersion}/anchor-${vVersion}-`
   );
-  
+
   // Replace tar extraction versions
   installationContent = installationContent.replace(
-    /tar -xvf anchor-v[\d.]+(?:-[\w.]+)?-/g,
+    /tar -xvf anchor-v[\d.]+-/g,
     `tar -xvf anchor-${vVersion}-`
   );