chore: bump version from 3.0.0 to 3.1.0 (#1886)

* chore: bump version from 3.0.0 to 3.1.0

Update version references across the entire codebase:
- Runtime version in onapplicationstart.cfc
- Package versions in box.json files
- CLI version in ModuleConfig.cfc
- Template and dependency constraints (^3.1.0)
- Documentation URLs (wheels.dev/3.1.0/)
- API reference URLs (wheels.dev/api/v3.1.0/)
- Docs sync workflow path
- Design docs and release candidate guide

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: update version field in templates/base/src/box.json to 3.1.0-SNAPSHOT

This file is the source of truth for ForgeBox published versions.
The dependency constraint was updated but the version field itself
was missed during the initial bump (was still 3.0.1-SNAPSHOT).

* refactor: inject -SNAPSHOT in workflow instead of source files

Source box.json files now use clean versions (e.g. 3.1.0) instead of
3.1.0-SNAPSHOT. The release workflow injects -SNAPSHOT for develop
builds and publishes stable versions from main — no file changes
needed when promoting develop to main.

Changes:
- release.yml: branch-aware version calculation adds -SNAPSHOT for develop
- release.yml: validation checks source files are clean (no SNAPSHOT)
- version-bump.yml: clean version inputs (patch/minor/major, no -snapshot)
- generate-changelog.yml: remove SNAPSHOT suffix stripping (no longer needed)
- box.json files: remove -SNAPSHOT suffix from version fields

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: bpamiri

.ai/wheels/configuration/overview.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The `/config` directory contains all configuration files for your Wheels application. In Wheels 3.0.0+, configuration was moved from `/app/config` to the root-level `/config` directory for better organization and clearer separation of concerns. These files control application behavior, database connections, routing, environment settings, and framework-wide defaults.
+The `/config` directory contains all configuration files for your Wheels application. In Wheels 3.1.0+, configuration was moved from `/app/config` to the root-level `/config` directory for better organization and clearer separation of concerns. These files control application behavior, database connections, routing, environment settings, and framework-wide defaults.
 
 ## File Structure and Purpose
 
@@ -87,7 +87,7 @@ if (get("environment") == "production") {
 
 ## Migration from Pre-3.0
 
-### Breaking Change in Wheels 3.0.0
+### Breaking Change in Wheels 3.1.0
 
 Configuration moved from `/app/config` to `/config` at root level.
 

.ai/wheels/configuration/routing.md

@@ -46,7 +46,7 @@ Define URL patterns and map them to controller actions:
 <cfscript>
     // Use this file to add routes to your application
     // Don't forget to reload after changes: ?reload=true
-    // See https://wheels.dev/3.0.0/guides/handling-requests-with-controllers/routing
+    // See https://wheels.dev/3.1.0/guides/handling-requests-with-controllers/routing
 
     mapper()
         // Resource-based routing (recommended)

.claude/settings.local.json

@@ -92,7 +92,9 @@
       "WebFetch(domain:helpx.adobe.com)",
       "WebFetch(domain:opencode.ai)",
       "Bash(lsof:*)",
-      "Bash(wc:*)"
+      "Bash(wc:*)",
+      "Bash(git merge-tree --write-tree origin/develop origin/feat/v3.1-internal-refactor 2>&1 | head -60)",
+      "Bash(git merge origin/develop --no-commit 2>&1)"
     ],
     "deny": []
   }

.github/workflows/docs-sync.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Sync docs into wheels.dev
         run: |
           # Guides: mirror with delete
-          rsync -av --del wheels/docs/src/ wheels-dev/docs/3.0.0/guides/
+          rsync -av --del wheels/docs/src/ wheels-dev/docs/3.1.0/guides/
 
           # Images: additive (no delete)
           rsync -av wheels/docs/src/.gitbook/assets/ wheels-dev/public/images/

.github/workflows/generate-changelog.yml

@@ -88,7 +88,6 @@ jobs:
         run: |
           # Detect version from box.json
           VERSION=$(jq -r '.version' templates/base/src/box.json)
-          VERSION="${VERSION%-SNAPSHOT}"
 
           BRANCH="changelog/$VERSION"
           git checkout -b "$BRANCH"

.github/workflows/release-candidate.yml

@@ -1,6 +1,6 @@
 # Release Candidate Workflow
 # This workflow builds and publishes Release Candidates for testing before final releases
-# Triggers on release candidate branches (e.g., release/3.0.0-rc.1)
+# Triggers on release candidate branches (e.g., release/3.1.0-rc.1)
 
 name: Wheels Release Candidate
 
@@ -33,7 +33,7 @@ jobs:
           pwd
           cat box.json
 
-          # Extract version from box.json (should be something like 3.0.0-rc.1)
+          # Extract version from box.json (should be something like 3.1.0-rc.1)
           VERSION=$(cat box.json | jq '.version' -r)
           echo "WHEELS_VERSION=${VERSION}+${{ github.run_number }}" >> $GITHUB_ENV
 

.github/workflows/release.yml

@@ -38,12 +38,17 @@ jobs:
           cd ./templates/base/src
           pwd
           cat box.json
-          echo "WHEELS_VERSION=`cat box.json | jq '.version' -r`+${{ github.run_number }}" >> $GITHUB_ENV
-          # main or snapshot
-          echo "BRANCH=main" >> $GITHUB_ENV
-          if [ $GITHUB_REF == 'refs/heads/develop' ]
-          then
+          BASE_VERSION=$(cat box.json | jq '.version' -r)
+          echo "Base version from box.json: ${BASE_VERSION}"
+          # Develop builds get -SNAPSHOT qualifier; main builds are stable releases.
+          # Source files keep clean versions (e.g. 3.1.0) so no changes are
+          # needed when promoting develop to main.
+          if [ "$GITHUB_REF" == "refs/heads/develop" ]; then
+            echo "WHEELS_VERSION=${BASE_VERSION}-SNAPSHOT+${{ github.run_number }}" >> $GITHUB_ENV
             echo "BRANCH=develop" >> $GITHUB_ENV
+          else
+            echo "WHEELS_VERSION=${BASE_VERSION}+${{ github.run_number }}" >> $GITHUB_ENV
+            echo "BRANCH=main" >> $GITHUB_ENV
           fi
 
       - name: Make build scripts executable
@@ -70,10 +75,13 @@ jobs:
             exit 1
           fi
 
-          # Check that version doesn't contain SNAPSHOT for main releases
-          if echo "$WHEELS_VERSION" | grep -qi "snapshot"; then
-            echo "ERROR: Version contains SNAPSHOT but this is a main branch release"
-            echo "Please remove SNAPSHOT suffix from box.json files before releasing."
+          # Check that source version in box.json is clean (no -SNAPSHOT suffix).
+          # The workflow injects -SNAPSHOT for develop builds automatically.
+          BASE_VERSION=$(jq -r '.version' templates/base/src/box.json)
+          if echo "$BASE_VERSION" | grep -qi "snapshot"; then
+            echo "ERROR: Version in box.json contains -SNAPSHOT suffix ($BASE_VERSION)"
+            echo "Source files should have clean versions (e.g., 3.1.0)."
+            echo "The workflow adds -SNAPSHOT automatically for develop builds."
             exit 1
           fi
 

.github/workflows/version-bump.yml

@@ -8,18 +8,18 @@ on:
   workflow_dispatch:
     inputs:
       new_version:
-        description: 'New version number (e.g., 3.0.1-SNAPSHOT or 3.1.0-SNAPSHOT)'
+        description: 'New version number (e.g., 3.1.1 or 3.2.0). No -SNAPSHOT suffix — the release workflow adds it automatically for develop builds.'
         required: true
         type: string
       bump_type:
         description: 'Type of version bump'
         required: true
         type: choice
         options:
-          - patch-snapshot
-          - minor-snapshot
-          - major-snapshot
-        default: patch-snapshot
+          - patch
+          - minor
+          - major
+        default: patch
 
 jobs:
   bump-version:
@@ -66,9 +66,7 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NEW_VERSION: ${{ github.event.inputs.new_version }}
         run: |
-          # Strip -SNAPSHOT suffix for changelog header
-          CHANGELOG_VERSION="${NEW_VERSION%-SNAPSHOT}"
-          ./tools/build/scripts/generate-changelog.sh "$CHANGELOG_VERSION" "" --write
+          ./tools/build/scripts/generate-changelog.sh "$NEW_VERSION" "" --write
 
       - name: Commit Changes
         env:

CONTRIBUTING.md

@@ -37,7 +37,7 @@ We welcome contributions via **Issues** and **Pull Requests (PRs)**. Before you
 * If it's a **security issue**, please use our [Responsible Disclosure Program](mailto:webmaster@wheels.dev?subject=Responsible%20Disclosure%20Program) — do not post it publicly.
 * Search existing Issues and PRs to avoid duplicates.
 * If your issue is urgent or blocking, you can leave a polite comment pinging the maintainers.
-* If you're new to contributing, check out the [Contributing to Wheels Guide](https://wheels.dev/3.0.0/guides/working-with-wheels/contributing-to-wheels) for tips and examples.
+* If you're new to contributing, check out the [Contributing to Wheels Guide](https://wheels.dev/3.1.0/guides/working-with-wheels/contributing-to-wheels) for tips and examples.
 
 ### Development Environment Setup
 
@@ -146,7 +146,7 @@ If you're making a **breaking change** or working on **core functionality**, it'
 ### Developing with Docker
 
 You can develop and test Wheels locally on multiple CFML engines using Docker.
-Follow the [Docker Instructions](https://wheels.dev/3.0.0/guides/working-with-wheels/contributing-to-wheels#developing-with-docker) to get set up quickly.
+Follow the [Docker Instructions](https://wheels.dev/3.1.0/guides/working-with-wheels/contributing-to-wheels#developing-with-docker) to get set up quickly.
 
 ---
 

MONOREPO.md

@@ -14,9 +14,9 @@ This document provides a comprehensive guide to understanding the Wheels 3.0 mon
 
 ## Overview
 
-Wheels 3.0 uses a monorepo structure to maintain all framework components in a single repository. This approach provides:
+Wheels 3.1 uses a monorepo structure to maintain all framework components in a single repository. This approach provides:
 
-- **Unified Versioning**: All components share the same version number (currently `3.0.0-rc.1`)
+- **Unified Versioning**: All components share the same version number (currently `3.1.0`)
 - **Simplified Development**: Changes across components can be developed and tested together
 - **Atomic Commits**: Related changes across CLI, core, and templates happen in single commits
 - **Easier Testing**: Cross-component integration testing without dependency management
@@ -96,7 +96,7 @@ box install wheels-cli
 
 ```
 core/
-├── box.json                      # Package metadata (v3.0.0-rc.1)
+├── box.json                      # Package metadata (v3.1.0)
 ├── src/
 │   └── wheels/                   # Framework code (27 directories)
 │       ├── controller/           # Controller base class
@@ -344,7 +344,7 @@ All components share the same version number defined in their `box.json` files.
 
 2. Update `CHANGELOG.md` with release notes
 
-3. Create git tag: `git tag v3.0.0`
+3. Create git tag: `git tag v3.1.0`
 
 4. Push and let CI/CD handle ForgeBox publishing
 
@@ -429,7 +429,7 @@ User's Application:
 
 ## Key Characteristics
 
-1. **Version Synchronization**: All components share version `3.0.0-rc.1`
+1. **Version Synchronization**: All components share version `3.1.0`
 2. **CFML-Based**: Framework written in CFML with CommandBox module system
 3. **Docker Testing**: Multi-engine and multi-database testing support
 4. **Template-Based Generation**: CLI uses Handlebars-style `{{variable}}` syntax
@@ -666,4 +666,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
 ---
 
 **Last Updated:** 2025-10-20
-**Version:** 3.0.0-rc.1
+**Version:** 3.1.0