Change management

Purpose

Changes to workers, routing, headers, and environment contracts can alter production behavior without obvious page diffs. This process ensures those changes are explicit, reviewed, and documented.

Changes requiring explicit management

• Worker route or wrangler.*.toml changes
• public/_headers and _redirects changes
• Auth/session behavior changes
• Environment variable additions/removals/semantic changes
• Page ownership/routing changes impacting sitemap, SEO, or protected paths

Required PR content

• What changed and why now
• Affected environments and hostnames
• Verification steps performed (commands + manual checks)
• Rollback steps
• Linked docs updates in this docs workspace

Documentation updates by change type

• Routing/ownership: update architecture/routing-reference.mdx
• Security/auth/CSP/CORS: update operations/security-model.mdx and operations/troubleshooting.mdx
• Config/env: update reference/configuration-reference.mdx and reference/environment-variables.mdx
• Release impacts: update operations/deployment-guide.mdx / operations/release-process.mdx

Approval guidance

• Route/header/worker/env changes should have at least one reviewer familiar with edge behavior.
• If uncertainty remains, deploy to staging first and capture evidence before production.