[#2596] Added installer support for multiple Vortex scaffold versions (1.x and 2.x).

.github/workflows/vortex-release.yml

@@ -30,6 +30,13 @@ jobs:
     outputs:
       release-version: ${{ steps.version.outputs.value }}
 
+    # The current major (built from this ref) and the other major (built from
+    # its '{N}.x' branch) are both derived from 'VORTEX_CURRENT_MAJOR' (default
+    # 1), so a single variable bump promotes a new major with no workflow edits.
+    env:
+      CURRENT_MAJOR: ${{ vars.VORTEX_CURRENT_MAJOR || '1' }}
+      OTHER_MAJOR: ${{ (vars.VORTEX_CURRENT_MAJOR || '1') == '1' && '2' || '1' }}
+
     steps:
       - name: Checkout code
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
@@ -85,13 +92,39 @@ jobs:
           ./build/installer.phar --no-interaction --no-cleanup --destination=test || exit 1
         working-directory: .vortex/installer
 
-      - name: Upload artifact
+      - name: Upload v${{ env.CURRENT_MAJOR }} installer artifact
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
-          name: vortex-installer
+          name: vortex-installer-v${{ env.CURRENT_MAJOR }}
           path: .vortex/installer/build/installer.phar
           if-no-files-found: error
 
+      # Build the other major's installer from its '{N}.x' branch so it is
+      # published alongside the current one. Checked out into a separate path so
+      # the current installer build above is untouched. Mirrors how the docs job
+      # pulls the other major's branch content.
+      - name: Checkout v${{ env.OTHER_MAJOR }} branch
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          ref: ${{ env.OTHER_MAJOR }}.x
+          path: vortex-v${{ env.OTHER_MAJOR }}
+          persist-credentials: false
+
+      - name: Build v${{ env.OTHER_MAJOR }} installer
+        run: |
+          composer install
+          sed -i "s/\"vortex-installer-version\": \"development\"/\"vortex-installer-version\": \"${OTHER_MAJOR}.x-dev\"/g" box.json
+          composer build
+          ./build/installer.phar --version
+        working-directory: vortex-v${{ env.OTHER_MAJOR }}/.vortex/installer
+
+      - name: Upload v${{ env.OTHER_MAJOR }} installer artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: vortex-installer-v${{ env.OTHER_MAJOR }}
+          path: vortex-v${{ env.OTHER_MAJOR }}/.vortex/installer/build/installer.phar
+          if-no-files-found: error
+
   vortex-release-docs:
     needs: vortex-release-installer
 
@@ -109,6 +142,10 @@ jobs:
       run:
         working-directory: docs
 
+    env:
+      CURRENT_MAJOR: ${{ vars.VORTEX_CURRENT_MAJOR || '1' }}
+      OTHER_MAJOR: ${{ (vars.VORTEX_CURRENT_MAJOR || '1') == '1' && '2' || '1' }}
+
     steps:
       - name: Checkout code
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
@@ -134,14 +171,33 @@ jobs:
         with:
           php-version: 8.3
 
-      - name: Download installer
+      - name: Download v1 installer
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
         with:
-          name: vortex-installer
+          name: vortex-installer-v1
+          path: installer-v1
 
-      - name: Copy installer to docs
+      - name: Download v2 installer
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: vortex-installer-v2
+          path: installer-v2
+
+      # Publish both installers. '/v1/install' and '/v2/install' are the stable
+      # per-major pins, always built from each major's own source. The bare
+      # '/install' is a copy of the current major's pin, selected by the
+      # 'VORTEX_CURRENT_MAJOR' repository variable (default 1) - bumping that one
+      # variable is the only action needed to promote a new major.
+      - name: Copy installers to docs
         run: |
-          cp ../installer.phar ../.vortex/docs/static/install
+          case "${CURRENT_MAJOR}" in
+            1|2) ;;
+            *) echo "Invalid VORTEX_CURRENT_MAJOR='${CURRENT_MAJOR}'. Expected 1 or 2."; exit 1 ;;
+          esac
+          mkdir -p ../.vortex/docs/static/v1 ../.vortex/docs/static/v2
+          cp ../installer-v1/installer.phar ../.vortex/docs/static/v1/install
+          cp ../installer-v2/installer.phar ../.vortex/docs/static/v2/install
+          cp "../.vortex/docs/static/v${CURRENT_MAJOR}/install" ../.vortex/docs/static/install
           php ../.vortex/docs/static/install --version
 
       - name: Check docs up-to-date
@@ -154,22 +210,25 @@ jobs:
         run: yarn install --frozen-lockfile
         working-directory: .vortex/docs
 
-      # Assemble the multi-version site for production: snapshot the released
-      # docs as v1 (served at the bare '/docs') and pull the '2.x'
-      # docs in as v2 (at '/docs/v2'). Mirrors the same step in
-      # 'vortex-test-docs.yml' (development / Netlify).
+      # Assemble the multi-version site for production: snapshot this ref's docs
+      # as the current major (served at the bare '/docs') and pull the other
+      # major's '{N}.x' branch docs in at '/docs/v{other}'. All driven by
+      # 'VORTEX_CURRENT_MAJOR'. Mirrors the same step in 'vortex-test-docs.yml'
+      # (development / Netlify).
       - name: Assemble versioned docs
         run: |
-          yarn docusaurus docs:version 1.x
-          git -C "${{ github.workspace }}" fetch origin 2.x --depth=1 || { echo "Failed to fetch the 2.x branch."; exit 1; }
-          git -C "${{ github.workspace }}" rev-parse --verify origin/2.x || { echo "The 2.x branch does not exist."; exit 1; }
+          yarn docusaurus docs:version "${CURRENT_MAJOR}.x"
+          git -C "${{ github.workspace }}" fetch origin "${OTHER_MAJOR}.x" --depth=1 || { echo "Failed to fetch the ${OTHER_MAJOR}.x branch."; exit 1; }
+          git -C "${{ github.workspace }}" rev-parse --verify "origin/${OTHER_MAJOR}.x" || { echo "The ${OTHER_MAJOR}.x branch does not exist."; exit 1; }
           rm -rf content
-          git -C "${{ github.workspace }}" checkout origin/2.x -- .vortex/docs/content || { echo "Failed to check out content from 2.x."; exit 1; }
+          git -C "${{ github.workspace }}" checkout "origin/${OTHER_MAJOR}.x" -- .vortex/docs/content || { echo "Failed to check out content from ${OTHER_MAJOR}.x."; exit 1; }
         working-directory: .vortex/docs
 
       - name: Build documentation site
         run: yarn run build
         working-directory: .vortex/docs
+        env:
+          VORTEX_CURRENT_MAJOR: ${{ env.CURRENT_MAJOR }}
 
       - name: Generate video for installer (not used in the final artifact)
         run: |

.github/workflows/vortex-test-docs.yml

@@ -19,6 +19,10 @@ jobs:
       statuses: write # Post pending/final commit statuses via 'gh api repos/.../statuses/...'.
       pull-requests: write # Post the Netlify preview link comment on the originating PR.
 
+    env:
+      CURRENT_MAJOR: ${{ vars.VORTEX_CURRENT_MAJOR || '1' }}
+      OTHER_MAJOR: ${{ (vars.VORTEX_CURRENT_MAJOR || '1') == '1' && '2' || '1' }}
+
     steps:
       # Post pending status to the PR commit.
       # Workflows triggered by workflow_run don't automatically report status
@@ -88,23 +92,55 @@ jobs:
         working-directory: '${{ github.workspace }}/.vortex/docs'
 
       # On the main (development) deploy, assemble the multi-version site:
-      # snapshot main's docs as v1 (served at the bare '/docs') and pull the
-      # '2.x' docs in as v2 (at '/docs/v2'). Skipped on PR/branch
-      # builds, which stay single-version previews. Mirrors the same step in
-      # 'vortex-release.yml' (production / GitHub Pages).
+      # snapshot main's docs as the current major (served at the bare '/docs')
+      # and pull the other major's '{N}.x' branch docs in at '/docs/v{other}'.
+      # Driven by 'VORTEX_CURRENT_MAJOR'. Skipped on PR/branch builds, which stay
+      # single-version previews. Mirrors the same step in 'vortex-release.yml'
+      # (production / GitHub Pages).
       - name: Assemble versioned docs
         if: github.event.workflow_run.head_branch == 'main'
         run: |
-          yarn docusaurus docs:version 1.x
-          git -C "${{ github.workspace }}" fetch origin 2.x --depth=1 || { echo "Failed to fetch the 2.x branch."; exit 1; }
-          git -C "${{ github.workspace }}" rev-parse --verify origin/2.x || { echo "The 2.x branch does not exist."; exit 1; }
+          yarn docusaurus docs:version "${CURRENT_MAJOR}.x"
+          git -C "${{ github.workspace }}" fetch origin "${OTHER_MAJOR}.x" --depth=1 || { echo "Failed to fetch the ${OTHER_MAJOR}.x branch."; exit 1; }
+          git -C "${{ github.workspace }}" rev-parse --verify "origin/${OTHER_MAJOR}.x" || { echo "The ${OTHER_MAJOR}.x branch does not exist."; exit 1; }
           rm -rf content
-          git -C "${{ github.workspace }}" checkout origin/2.x -- .vortex/docs/content || { echo "Failed to check out content from 2.x."; exit 1; }
+          git -C "${{ github.workspace }}" checkout "origin/${OTHER_MAJOR}.x" -- .vortex/docs/content || { echo "Failed to check out content from ${OTHER_MAJOR}.x."; exit 1; }
         working-directory: '${{ github.workspace }}/.vortex/docs'
 
+      # On the main deploy, publish both installers to match the multi-version
+      # docs: '/v1/install' and '/v2/install' are the stable per-major pins and
+      # the bare '/install' is a copy of the current major's pin (the
+      # 'VORTEX_CURRENT_MAJOR' repository variable, default 1). The downloaded
+      # installer above is the current major (built from 'main'); the other
+      # major is built from its '{N}.x' branch. Mirrors 'vortex-release.yml'.
+      - name: Checkout v${{ env.OTHER_MAJOR }} branch
+        if: github.event.workflow_run.head_branch == 'main'
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          ref: ${{ env.OTHER_MAJOR }}.x
+          path: vortex-v${{ env.OTHER_MAJOR }}
+          persist-credentials: false
+
+      - name: Build and publish v${{ env.OTHER_MAJOR }} installer
+        if: github.event.workflow_run.head_branch == 'main'
+        run: |
+          case "${CURRENT_MAJOR}" in
+            1|2) ;;
+            *) echo "Invalid VORTEX_CURRENT_MAJOR='${CURRENT_MAJOR}'. Expected 1 or 2."; exit 1 ;;
+          esac
+          composer --working-dir="vortex-v${OTHER_MAJOR}/.vortex/installer" install
+          sed -i "s/\"vortex-installer-version\": \"development\"/\"vortex-installer-version\": \"${OTHER_MAJOR}.x-dev\"/g" "vortex-v${OTHER_MAJOR}/.vortex/installer/box.json"
+          composer --working-dir="vortex-v${OTHER_MAJOR}/.vortex/installer" build
+          mkdir -p .vortex/docs/static/v1 .vortex/docs/static/v2
+          cp .vortex/docs/static/install ".vortex/docs/static/v${CURRENT_MAJOR}/install"
+          cp "vortex-v${OTHER_MAJOR}/.vortex/installer/build/installer.phar" ".vortex/docs/static/v${OTHER_MAJOR}/install"
+          cp ".vortex/docs/static/v${CURRENT_MAJOR}/install" .vortex/docs/static/install
+
       - name: Build documentation site
         run: yarn run build
         working-directory: '${{ github.workspace }}/.vortex/docs'
+        env:
+          VORTEX_CURRENT_MAJOR: ${{ env.CURRENT_MAJOR }}
 
       # This workflow runs via 'workflow_run', where 'github.ref' is always the
       # default branch, so the action's branch-based production detection cannot

.vortex/docs/.gitignore

@@ -28,5 +28,7 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
-# Copied installer file.
+# Copied installer files (the bare active-major path and the per-major pins).
 static/install
+static/v1/install
+static/v2/install

.vortex/docs/content/contributing/maintenance/release.mdx

@@ -43,13 +43,15 @@ When creating a new release, determine the version based on the changes:
 
 ### Branch strategy
 
-- **`main`** - Current stable release branch (always the latest major version)
-- **`project/X.x`** - Development branch for the next major version (e.g., `project/2.x`)
-- **`X.x`** - Maintenance branches for older major versions (e.g., `1.x` after `2.x` is released)
+- **`main`** - the current major version under active development (`1.x` today)
+- **`2.x`** - a development branch for an upcoming major version, ahead of `main` (future majors follow the same pattern: `3.x`, `4.x`, ...)
+- **`1.x`** - a maintenance branch for a superseded major version, behind `main` (for example `1.x` once `main` holds `2.x`)
 
-When a new major version is ready:
-1. The next major version development in `project/X.x` is merged into `main`
-2. The previous major version code is preserved in its own `X.x` branch for maintenance
+Promoting a new major version is a single action: set the `VORTEX_CURRENT_MAJOR` repository variable to its number. The documentation default and the installer's bare `/install` URL both follow it, while the per-major docs and `/v{N}/install` pins are always published.
+
+When `main` advances to a new major version:
+1. The upcoming major's branch (for example `2.x`) is merged into `main`
+2. The superseded major continues on its own branch (for example `1.x`) for maintenance
 
 :::note
 

.vortex/docs/content/installation.mdx

@@ -44,6 +44,19 @@ curl -SsL https://www.vortextemplate.com/install > installer.php && php installe
 
 :::
 
+:::tip Choosing a Vortex version
+
+The command above installs the current stable **Vortex** release (the `1.x` line
+today). To target a specific major version explicitly, use its dedicated path:
+
+- `https://www.vortextemplate.com/v1/install` - the current `1.x` line.
+- `https://www.vortextemplate.com/v2/install` - the `2.x` line, currently in development.
+
+Once installed, `ahoy update-vortex` keeps your project on its major version - it
+never jumps across a major release. See [Updating Vortex](./updating-vortex).
+
+:::
+
 ### 2. Commit the initial project structure
 
 ```shell

.vortex/docs/content/updating-vortex.mdx

@@ -21,6 +21,16 @@ After the update, review and commit the changes to your project to maintain vers
 We recommend updating **Vortex** monthly or at least quarterly to keep your project
 secure and up-to-date.
 
+:::note Staying on your major version
+
+`ahoy update-vortex` updates your project **within its current major version** - a
+`1.x` project receives the latest `1.x` release and is never moved to `2.x`
+automatically. Moving to a new major is a deliberate step: run that major's
+installer (for example `https://www.vortextemplate.com/v2/install`) against your
+project.
+
+:::
+
 ## Before updating
 
 Check the release notes for the latest version to understand what has changed

.vortex/docs/docusaurus.config.js

@@ -18,6 +18,16 @@ import {themes as prismThemes} from 'prism-react-renderer';
 // CI; it is never committed to a branch.
 const versioned = fs.existsSync('versioned_docs');
 
+// The current major (the 'VORTEX_CURRENT_MAJOR' repository variable, default 1)
+// drives the whole site: its docs are a snapshot under 'versioned_docs/' served
+// as the default at the bare '/docs', and the live 'content/' (pulled from the
+// other major's '{N}.x' branch in CI) is served at '/docs/v{other}'. Bumping
+// that one variable promotes a new major - nothing else changes here.
+const currentMajor = process.env.VORTEX_CURRENT_MAJOR || '1';
+const otherMajor = currentMajor === '1' ? '2' : '1';
+const currentDocsVersion = `${currentMajor}.x`;
+const otherIsNewer = Number(otherMajor) > Number(currentMajor);
+
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: 'Vortex - Drupal project template',
@@ -58,22 +68,20 @@ const config = {
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
           editUrl: 'https://github.com/drevops/vortex/tree/main/.vortex/docs/',
-          // In versioned (aggregate) builds, v1 is the snapshot in
-          // 'versioned_docs/' served at the bare '/docs' (the default), and
-          // the current 'content/' is v2 at '/docs/v2'. To flip the default
-          // when 2.x is ready: set `lastVersion: 'current'`, give '1.x' a
-          // `path: 'v1'`, drop the v2 `path` so 'current' serves at the bare
-          // '/docs', and swap the '/docs/v1' redirect below for '/docs/v2'.
+          // In versioned (aggregate) builds the current major is the snapshot
+          // in 'versioned_docs/' served at the bare '/docs' (the default), and
+          // the live 'content/' is the other major at '/docs/v{other}'. Both
+          // are derived from 'VORTEX_CURRENT_MAJOR' - no manual edits to flip.
           ...(versioned ? {
-            lastVersion: '1.x',
+            lastVersion: currentDocsVersion,
             versions: {
-              '1.x': {
-                label: 'v1',
+              [currentDocsVersion]: {
+                label: `v${currentMajor}`,
               },
               current: {
-                label: 'v2',
-                path: 'v2',
-                banner: 'unreleased',
+                label: `v${otherMajor}`,
+                path: `v${otherMajor}`,
+                banner: otherIsNewer ? 'unreleased' : 'unmaintained',
               },
             },
           } : {}),
@@ -233,11 +241,10 @@ const config = {
       '@docusaurus/plugin-client-redirects',
       {
         redirects: [
-          // In versioned builds, 'v1' is the default at the bare '/docs', so
-          // its explicit path redirects there. When the default flips to
-          // 'v2', change this to redirect '/docs/v2' instead.
+          // The current major is the default at the bare '/docs', so its
+          // explicit '/docs/v{current}' path redirects there.
           ...(versioned ? [{
-            from: '/docs/v1',
+            from: `/docs/v${currentMajor}`,
             to: '/docs',
           }] : []),
           {