Add versioned docs, bump development version to 1.1.0

.github/workflows/deploy_docs.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - main
     tags:
-      - 'v[0-9]+.[0-9]+.0'
+      - 'v*.*.*'
   workflow_dispatch:
 
 permissions:
@@ -18,7 +18,49 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    outputs:
+      should_deploy: ${{ steps.evaluate.outputs.should_deploy }}
+      doc_version: ${{ steps.evaluate.outputs.doc_version }}
+      skip_reason: ${{ steps.evaluate.outputs.skip_reason }}
+    steps:
+      - name: Evaluate deployment target
+        id: evaluate
+        shell: bash
+        run: |
+          should_deploy=false
+          doc_version=
+          skip_reason=
+
+          if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" || "${GITHUB_REF}" == "refs/heads/main" ]]; then
+            should_deploy=true
+          elif [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            if [[ "${GITHUB_REF_NAME}" == *-* ]]; then
+              skip_reason="Skipping documentation deployment for prerelease tag ${GITHUB_REF_NAME}."
+            elif [[ "${GITHUB_REF_NAME}" =~ ^v([0-9]+)\.([0-9]+)\.0$ ]]; then
+              should_deploy=true
+              doc_version="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}"
+            else
+              skip_reason="Skipping documentation deployment for patch tag ${GITHUB_REF_NAME}."
+            fi
+          else
+            skip_reason="Skipping documentation deployment for ref ${GITHUB_REF}."
+          fi
+
+          {
+            echo "should_deploy=${should_deploy}"
+            echo "doc_version=${doc_version}"
+            echo "skip_reason=${skip_reason}"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Report skipped deployment
+        if: steps.evaluate.outputs.should_deploy != 'true'
+        run: echo "${{ steps.evaluate.outputs.skip_reason }}"
+
   build:
+    needs: prepare
+    if: needs.prepare.outputs.should_deploy == 'true'
     runs-on: ubuntu-latest
     defaults:
       run:
@@ -40,16 +82,16 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Create versioned docs on tag push
-        if: startsWith(github.ref, 'refs/tags/v')
+      - name: Create versioned docs on qualifying tag push
+        if: needs.prepare.outputs.doc_version != ''
         run: |
-          FULL_VERSION="${GITHUB_REF#refs/tags/v}"
-          # Extract major.minor for the doc version (e.g., v3.1.0 -> 3.1.x)
-          MAJOR="$(echo "$FULL_VERSION" | cut -d. -f1)"
-          MINOR="$(echo "$FULL_VERSION" | cut -d. -f2)"
-          DOC_VERSION="${MAJOR}.${MINOR}.x"
-          echo "Creating docs version ${DOC_VERSION}"
-          npx docusaurus docs:version "${DOC_VERSION}"
+          DOC_VERSION="${{ needs.prepare.outputs.doc_version }}"
+          if [[ -f versions.json ]] && grep -q "\"${DOC_VERSION}\"" versions.json; then
+            echo "Docs version ${DOC_VERSION} already exists; skipping snapshot creation."
+          else
+            echo "Creating docs version ${DOC_VERSION}"
+            npx docusaurus docs:version "${DOC_VERSION}"
+          fi
 
       - name: Build site
         run: npm run build
@@ -65,11 +107,12 @@ jobs:
           path: src/CrestApps.Core.Docs/build
 
   deploy:
+    if: needs.prepare.outputs.should_deploy == 'true'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-    needs: build
+    needs: [prepare, build]
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

Directory.Build.props

@@ -45,7 +45,7 @@
   </ItemGroup>
 
   <PropertyGroup>
-    <VersionPrefix>1.0.0</VersionPrefix>
+    <VersionPrefix>1.1.0</VersionPrefix>
     <!-- VersionSuffixBase is the label passed in from the command line (e.g. "preview").
          VersionSuffix is assembled here so the build number is always appended when provided.
          Passing /p:VersionSuffix=... on the command line would create a global MSBuild property
@@ -134,11 +134,10 @@
     <NoWarn>$(NoWarn);NU1605</NoWarn>
 
     <!-- NU5104: A stable release of a package should not have a prerelease dependency.
-         CrestApps.Core 1.0.0 ships against .NET 10 preview ecosystem packages (notably
+         CrestApps.Core ships against .NET 10 preview ecosystem packages (notably
          Microsoft.Extensions.DataIngestion, A2A.AspNetCore, Lucene.Net.Analysis.Common)
-         that are still pre-release at the time of this release. The 1.0.0 release notes
-         document this explicitly. Re-enable this warning once those upstream packages ship
-         stable releases. -->
+         that are still pre-release at the time of release. Re-enable this warning once
+         those upstream packages ship stable releases. -->
     <NoWarn>$(NoWarn);NU5104</NoWarn>
 
     <NoWarn>$(NoWarn),1573,1591,1712</NoWarn>

src/CrestApps.Core.Docs/README.md

@@ -19,3 +19,29 @@ npm run build
 ```
 
 This site contains the framework-only documentation for `CrestApps.Core`.
+
+## Versioning
+
+The site keeps a version selector so older releases stay available while `main`
+continues to evolve. The unversioned `docs/` folder is the **Latest** version and
+tracks `main`. Each released version is frozen under `versioned_docs/` and
+`versioned_sidebars/`, with the list of published versions in `versions.json`.
+
+Versions are created automatically on qualifying tag pushes (`vX.Y.0`) by the
+`deploy_docs.yml` GitHub Actions workflow, which snapshots the current docs as
+`X.Y` (for example, `v1.0.0` produces the `1.0` version, served under `/docs/1.0/`).
+To cut a version manually:
+
+```bash
+npx docusaurus docs:version 1.0
+```
+
+Commit the generated `versioned_docs/`, `versioned_sidebars/`, and `versions.json`
+so the frozen version persists across future deployments.
+
+## Deployment
+
+The site is deployed automatically to GitHub Pages via the `deploy_docs.yml`
+workflow on every push to `main`, on `vX.Y.0` release tag pushes, and on manual
+`workflow_dispatch` runs. Prerelease tags (for example `v1.0.0-rc.1`) and patch
+tags (for example `v1.0.1`) are intentionally skipped.

src/CrestApps.Core.Docs/docs/changelog/index.md

@@ -11,4 +11,5 @@ This section tracks `CrestApps.Core` releases and notable repository-level chang
 
 | Version | Highlights |
 | --- | --- |
+| [1.1.0](v1.1.0) | Next release, currently in development (nightly and preview builds) |
 | [1.0.0](v1.0.0) | Initial standalone release plus merged configuration catalogs, automatic AI tool dependency expansion, clearer quick-start guidance, and deployment configuration diagnostics |

src/CrestApps.Core.Docs/docs/changelog/v1.1.0.md

@@ -0,0 +1,20 @@
+---
+sidebar_label: 1.1.0 Release Notes
+sidebar_position: 3
+title: "Version 1.1.0 Release Notes"
+description: Release notes for the upcoming CrestApps.Core 1.1.0 release.
+---
+
+# Version 1.1.0 Release Notes
+
+**Package version**: `1.1.0`
+
+:::info
+`CrestApps.Core` 1.1.0 is the next release and is currently in development. Nightly
+and preview builds are published from `main` under the `1.1.0` version prefix. This
+page will be updated as changes land after 1.0.0.
+:::
+
+## Highlights
+
+_No changes yet. Highlights will be documented here as features are merged for 1.1.0._