docs(docs): v4 guides phase 2c — ship deployment, contributing, upgrading, glossary#2181
Merged
Conversation
… glossary Closes the gap flagged in the post-merge correction on PR #2169: those four sections shipped as placeholder stubs only, not the content the PR body described. Plan scopes 14 pages (6 Deployment + 4 Contributing + 3 Upgrading + Glossary rewrite) plus sidebar wiring, scoped .ai/ audit, and completion report. Scope decisions recorded in the plan: - Deployment teaches user-authored Dockerfiles + nginx/systemd (no wheels docker/wheels deploy commands fabricated — neither exists in v4) - Kamal port: one sentence + link from deployment/index.mdx to the implementation plan, with grep-able TODO to swap to PR URL later - Dockerfile reference is Lucee 7 canonical; others mentioned in a note - upgrading/2x-to-3x is a ~1-screen pointer to v3.0 guides - Glossary hand-curated from Phase 2a/2b terms, ~30-50 entries - .ai/ audit scoped to Phase 2c topics, not a full sweep Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Explains the two deployment models Wheels supports today (Docker, VM) and the "what the framework gives you vs what you assemble" boundary. Notes that wheels deploy (Kamal port) is in active development, with a grep-able TODO to swap the placeholder for a PR/issue link once one exists. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…r prod Covers config/environment.cfm + settings.cfm production overrides, env-var resolution via application.wo.env() (framework → .env file → JVM env), the auto-flips production applies (showErrorInformation=false, caching on, autoMigrateDatabase=false), and a 10-item pre-boot checklist with source anchors in the framework CFCs that enforce each item. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Teaches packaging a wheels app as a docker image. Multi-stage dockerfile (node builder + lucee/lucee:7-tomcat10-jre21 runtime), .dockerignore, compose with redis sidecar and required-env guards, split /health + /ready endpoints, image-size tips, multi-arch buildx, and Adobe/BoxLang base-image swap hints. Explicit that wheels docker/wheels deploy do not exist in 4.0 — readers use plain docker and docker compose CLIs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Covers lucee 7 + java 21 install, /opt/myapp/{current,releases,shared}
release layout, systemd unit (User=lucee, EnvironmentFile, Restart=on-failure),
nginx reverse proxy with TLS termination, and a zero-downtime rsync → migrate
→ ln -sfn swap sequence. CommandBox fallback noted for teams that prefer
box server. No fabricated wheels commands — plain ssh, rsync, systemctl.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ives Documents every header + setting in vendor/wheels/middleware/SecurityHeaders.cfc with source line citations, the CSRF enforcement path (authenticityTokenField → $runCsrfProtection → $verifyAuthenticityToken), HSTS auto-default in production, trusted proxy handling, reloadPassword rotation, and secret management. Flags the missing HSTS off-switch as a known limitation linked to issue #2174 rather than fabricating a non-existent parameter. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Covers the RequestId middleware (X-Request-Id, UUID per request), structured logging patterns, a minimal Health controller with /healthz + /readyz split, Sentry package activation (cp -r packages/sentry vendor/sentry) with what it instruments and the known job-error gap, and external APM options (Datadog, New Relic, OpenTelemetry) since wheels ships no first-party metrics. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Explains project governance (core team via git log — no CODEOWNERS file yet), the four ways to contribute (code, docs, packages, issue triage), and links the existing CODE_OF_CONDUCT.md (Contributor Covenant v2.0). CardGrid to pull-requests, coding-standards, writing-docs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Step-by-step PR workflow. Cites commitlint.config.js directly for the valid types + scope-enum (23 scopes spanning model, controller, view, router, middleware, migration, cli, test, config, di, job, mailer, plugin, sse, seed, docs, web, web/ui, web/landing, web/blog, web/guides, web/api, web/starlight). Requires bash tools/test-local.sh before push. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…compat Covers camelCase naming, component access modifiers (public for mixin integration, $-prefix for internal scope), and the top cross-engine gotchas from .ai/wheels/cross-engine-compatibility.md: struct.map() collision, Adobe CF application scope, closure this, bracket-notation function calls in closures, array-by-value in struct literals, createDynamicProxy Lucee 7 semantics, and the private mixin function trap. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Walks a contributor through the docs workflow: frontmatter shapes (howto,
reference, section), Diátaxis typing, the three {test:*} directives sourced
from scripts/verify-docs/VALIDATION.md (compile, cli, tutorial), running
pnpm verify:docs + pnpm build locally, and sidebar wiring via the version
JSON file. Close with the common mdx/cfml gotchas that trip up first-time
contributors.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Framework version sourced from vendor/wheels/events/onapplicationstart.cfc (application.\$wheels.version = 4.0.0). CHANGELOG.md header confirms Keep-a-Changelog + SemVer. Release cadence described from actual git tag history (no fabricated schedule). CardGrid to 3x-to-4x (critical) and 2x-to-3x (pointer). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Documents every 3.x → 4.0 breaking change with CHANGELOG + PR citations: CORS deny-all (#2039), HSTS production default (#2081), CSRF key required (#2079, #2086), allowEnvironmentSwitchViaUrl production flip (#2076), RateLimiter trustProxy=false (#2024, #2088), CSRF SameSite cookie (#2035), wheels snippets → wheels code (#1852), wheels.Test → wheels.WheelsTest (#1889), tests/specs/functions/ → functional/ (#1872), wirebox → wheelsdi (#1888). Deprecations: plugins/ (#1995), paginationLinks (#1930), RocketUnit (#1925), HTTP MCP endpoint. Removed: RocketUnit core, Railo shim (#1987), server.cfc (#1902). Worked example of plugin → package port with provides.mixins explicit opt-in. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Short pointer (~200 words). Directs readers to the frozen v3.0 guides for the 2→3 hop and the sibling 3x-to-4x page for the second hop. Explains why skipping intermediate upgrades is expensive: each major's breaking changes assume the previous version's semantics. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Alphabetized reference with one-sentence definitions and links back to the guide page where each concept is fully explained. Curated from core-concepts, basics, and digging-deeper pages. Terms cut as too generic (Controller, View, Model standalone) or lacking a conceptual anchor in Phase 2a/2b (Mailer, WheelsTest, Strong params). Automation deferred to a later polish pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Populates three previously-empty sidebar groups with the new Phase 2c pages: Deployment & Operations (5 child items), Contributing & Project (3 child items), Upgrading (2 child items). Glossary entry unchanged — it's already a single-link row. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 2c deployment/production-config.mdx and deployment/security-hardening.mdx now cover the same territory with cited source anchors. Kept .ai/wheels/security/https-detection.md (scoped to the isSecure() controller helper, not deployment configuration) and .ai/wheels/cross-engine-compatibility.md (contributor-facing reference used by contributing/coding-standards.mdx). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
16 commits, 14 content pages (6 deployment + 4 contributing + 3 upgrading + 1 glossary rewrite), sidebar wired, 2 .ai/ files retired. Final build green at 340 pages; verify:docs green at 43/43 tagged blocks. Per-page drift captured with source-verification wins and six carryover items for follow-up work. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three findings from pr-review-toolkit:code-reviewer: 1. upgrading/3x-to-4x.mdx — removed fabricated SecurityHeaders(hsts=false) API call. vendor/wheels/middleware/SecurityHeaders.cfc has no hsts boolean; real parameter is strictTransportSecurity (string), and empty string auto-falls-back to the production default. Page now honestly notes the off-switch gap (#2174) with a "strip at your reverse proxy" workaround. 2. deployment/docker-deployment.mdx — fixed broken LinkCard href from core-concepts/middleware/ (no such page) to core-concepts/middleware-pipeline/. 3. contributing/coding-standards.mdx — replaced broken LinkCard href pointing at non-existent troubleshooting/cross-engine-compatibility/ with a link to contributing/pull-requests (sibling page). Build + verify:docs green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…link Legacy `cfwheels/cfwheels` org and `main` branch — the repo is `wheels-dev/wheels` and the default branch is `develop`.
4 tasks
5 tasks
bpamiri
added a commit
that referenced
this pull request
May 6, 2026
…#2429) The link from /v4-0-0-snapshot/upgrading/2x-to-3x/ to the v3 Config Directory Migration page 404'd because the file was named 3.0.0-config-migration.md and Astro's slug generator strips dots entirely rather than converting them to dashes, producing the unintuitive URL /v3-0-0/upgrading/300-config-migration/. PR #2181 introduced the link assuming dots-to-dashes — that assumption was incorrect. - Rename file to 3-0-0-config-migration.md so the URL matches every other doc filename in the tree and the existing link works as written. - Add redirect from /300-config-migration/ to preserve any external bookmarks accumulated while the dotted-slug URL was live. - Add a sidebar entry under INTRODUCTION > Upgrading; the page was orphaned from v3-0-0.json entirely. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Delivers Phase 2c of the v4 guides rewrite — the sections that #2169 described as shipped but landed as placeholder stubs. Context: that PR's description was corrected post-merge; this PR closes the gap.
14 new/rewritten pages + sidebar wiring + scoped
.ai/audit + plan/report pair. All claims source-verified against framework CFCs, middleware, CHANGELOG entries, and commitlint config.Final state: 340 rendered pages, 62 validated
{test:*}harness blocks across the Phase 2c diff (all pass on clean run),pnpm buildgreen,pnpm verify:docsgreen.What shipped
v4-0-0-snapshot.json.ai/auditconfiguration/security.md,security/csrf-protection.md) — superseded by new pagesScope decisions (resolved in the plan)
deployment/index.mdxnotes thewheels deployport is in active development and links kamal-deploy.org. A grep-ableTODO(phase-2c)JSX comment flags where to swap the placeholder once a PR/issue exists.wheels docker *andwheels deploydo not exist in v4. Deployment docs teach user-authored Dockerfiles + nginx/systemd directly.2x-to-3x= short pointer — v3.0 guides are still frozen and authoritative for that hop. Duplicating created drift risk..ai/audit scoped — matches Phase 2b-CLI precedent. Full sweep remains on the design spec's end-of-Phase-2 list.Source-verification wins
Drift caught by subagents before commit:
SecurityHeaders(hsts=false)parameter does not exist —SecurityHeaders.cfc:23-31exposesstrictTransportSecurity(string), and empty string auto-falls-back to the production default.upgrading/3x-to-4x.mdxnow honestly documents the off-switch gap (#2174) instead of fabricating the API.docs/superpowers/plans/2026-04-20-wheels-deploy-kamal-port.mdis on an unmerged branch, notdevelop. Link replaced with kamal-deploy.org + TODO.SecurityHeadersdefault + config option cites the exact line ofSecurityHeaders.cfcthat sets it.vendor/wheels/Job.cfc:345, 368only writes towheels_jobslog). Gap documented in-page.commitlint.config.js, not paraphrased from CLAUDE.md.3x-to-4x.mdxcites a CHANGELOG entry or PR number.Test plan
pnpm verify:docson Phase 2c diff — 62/62 blocks passpnpm build— 340 pages, no broken-link warnings.mdxfilepr-review-toolkit:code-reviewer— 3 findings surfaced, all 3 fixed (5b8d463)Known carryover (non-blocking)
Tracked in the Phase 2c report:
wheels deploydesign + implementation plan merge to develop (currently onclaude/interesting-cartwright-ed6357), swap thedeployment/index.mdxTODO for a concrete linkcontributing/index.mdxself-verifyingsecurity-hardening.mdx+3x-to-4x.mdxdocument the gap; closing lets us remove the caution notesdocs/releases/blog-skeletons/02-upgrading-from-3x.mdcontains claims (legacyCompatibilityAdapteras a settings flag, parallel-runner as must-do) that didn't verify against current source; skeleton may need updating to match shipped3x-to-4xpageArtifacts
docs/superpowers/plans/2026-04-21-guides-rewrite-phase-2c.mddocs/superpowers/plans/2026-04-21-guides-rewrite-phase-2c-report.md🤖 Generated with Claude Code