sets up a parallel build of docs

.github/workflows/build_documentation.yml

@@ -15,13 +15,23 @@ concurrency:
 
 jobs:
   build-docs:
-    name: Build combined documentation
+    name: Build combined documentation (${{ matrix.slug }})
     if: github.event_name != 'schedule' || github.repository == 'swiftlang/docs'
     runs-on: ubuntu-latest
     container:
       image: swiftlang/swift:nightly-main-jammy
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - slug: main
+            ref: main
+          - slug: "6.4"
+            ref: release/6.4.x
     steps:
       - uses: actions/checkout@v7
+        with:
+          ref: ${{ matrix.ref }}
 
       # - uses: actions/cache@v6
       #   with:
@@ -37,9 +47,9 @@ jobs:
         run: python3 scripts/build_docs.py --output-dir "$GITHUB_WORKSPACE/build-output"
 
       - name: Package build output
-        run: tar -czf "$GITHUB_WORKSPACE/combined-documentation.tar.gz" -C "$GITHUB_WORKSPACE/build-output" .
+        run: tar -czf "$GITHUB_WORKSPACE/combined-documentation-${{ matrix.slug }}.tar.gz" -C "$GITHUB_WORKSPACE/build-output" .
 
       - uses: actions/upload-artifact@v7
         with:
-          name: combined-documentation
-          path: combined-documentation.tar.gz
+          name: combined-documentation-${{ matrix.slug }}
+          path: combined-documentation-${{ matrix.slug }}.tar.gz

scripts/README.md

@@ -76,3 +76,17 @@ python3 scripts/validate_navigation.py --archive path/to/combined.doccarchive
 
 `--navigation` and `--sources` can override the input files for experimentation.
 
+## Building multiple branches (main + release branches)
+
+`build_documentation.yml`'s `build-docs` job builds two variants of
+the documentation - using a matrix keyed by branch - for `main` and the latest
+release branch (such as `release/6.4.x.
+
+There isn't a shared multi-version file or `--sources` override — each release branch
+owns and maintains its own manifest.
+
+### Adding a new release branch
+
+When a new release branch gets established, we start with branch creation, update its
+`sources.json`, then add or update the entry to the `matrix.include` list in
+`build_documentation.yml` on `main`.

scripts/sources.json

@@ -1,6 +1,6 @@
 {
   "version": {
-    "slug": "latest"
+    "slug": "main"
   },
   "sources": [
     {