[Workers] Restructure versions and deployments docs by ajhawkings · Pull Request #31787 · cloudflare/cloudflare-docs

ajhawkings · 2026-06-29T20:37:28Z

Summary

Promotes versions & deployments to a top-level section under Workers and restructures it. Separates out a "deployment management" which allows the overview page to become a proper summary. And separates the instructions for setting up version affinity into a new page.

Aim: make our existing primitives clearer for devs and do groundwork for skew protection and automatic version affinity documentation when they launch

Preview: https://ajhawkings-restructure-versions-and-deployments.preview.developers.cloudflare.com/workers/versions-and-deployments/

Changes

Move versions & deployments to top level

Versions and deployments moved from /workers/configuration/versions-and-deployments/ to /workers/versions-and-deployments/
This is a growing section with multiple sub-pages (and now subsections) - including version affinity (added in this PR) and skew protection (coming soon). I think it is important for it to be top-level
All internal links and redirects updated accordingly

Overview page split into two

Overview becomes explainer on what versions and deployments are as separate concepts and the default behaviour
New Deployment management page Houses the how-to content for uploading versions without deploying, deploying via Wrangler/dashboard

Gradual deployments section

Converted to sub-section with overview page, to cope with a separate version affinity page. This is needed to better document our existing primitives and to do the groundwork for adding more documentation for when we ship automatic version affinity. (durable object gradual deployments also extracted to separate page - I think this works better but not 100% necessary)
Added version skew during gradual deployments section: explains the two forms (within a Worker, between Workers) and points to solutions

New Version affinity page

Dedicated page explaining the Cloudflare-Workers-Version-Key header nested under Gradual deployments
Decision tree for choosing a version key: authenticated apps (user ID), session-based apps, anonymous/cookieless apps (IP-based or self-managed cookie)
Static assets section explaining the fingerprinted asset mismatch problem (404s during gradual rollouts)
The separate static assets gradual rollouts page included some good guidance but was hidden away under advanced - so has been folded into this page with a redirect created

Documentation checklist

The change adheres to the documentation style guide.
Files which have changed name or location have been allocated redirects.

Relocate the versions and deployments pages from /workers/configuration/versions-and-deployments/ to /workers/versions-and-deployments/ and update all internal links and redirects accordingly.

Restructure the versions and deployments section to improve clarity around gradual deployments, version skew, and version affinity. Changes: - Split the overview page into an overview and a separate deployment management page - Convert gradual-deployments into a directory with sub-pages - Create dedicated version affinity page with decision tree for authenticated, session-based, and anonymous applications - Extract Durable Objects section into its own page under gradual deployments - Add version skew framing to the gradual deployments page - Add disambiguation note to version overrides page - Fold static assets gradual rollouts content into version affinity page and redirect the old page Note: The static assets section on the version affinity page is temporary and will be replaced with a link to skew protection documentation when that feature launches.

github-actions · 2026-06-29T20:37:51Z

This PR changes current filenames or deletes current files. Make sure you have redirects set up to cover the following paths:

/workers/configuration/versions-and-deployments/gradual-deployments/
/workers/configuration/versions-and-deployments/
/workers/configuration/previews/
/workers/configuration/versions-and-deployments/rollbacks/
/workers/configuration/versions-and-deployments/version-overrides/

github-actions · 2026-06-29T20:38:09Z

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
`*`	`@cloudflare/product-owners`
`/public/__redirects`	`@cloudflare/content-engineering`, `@cloudflare/product-owners`
`/src/content/changelog/`	`@cloudflare/pm-changelogs`, `@cloudflare/product-owners`
`/src/content/docs/cloudflare-for-platforms/workers-for-platforms/`	`@irvinebroque`, `@dinasaur404`, `@cloudflare/deploy-config`, `@cloudflare/product-owners`
`/src/content/docs/containers/`	`@mikenomitch`, `@th0m`, `@cloudflare/product-owners`, `@cloudflare/cloudchamber`
`/src/content/docs/durable-objects/`	`@elithrar`, `@rita3ko`, `@irvinebroque`, `@vy-ton`, `@iglesiasbrandon`, `@joshthoward`, `@danlapid`, `@oxyjun`, `@lambrospetrou`, `@mikenomitch`, `@cloudflare/product-owners`
`/src/content/docs/hyperdrive/`	`@elithrar`, `@rita3ko`, `@irvinebroque`, `@vy-ton`, `@ivoryibu`, `@thomasgauvin`, `@sejoker`, `@oxyjun`, `@knickish`, `@cloudflare/product-owners`
`/src/content/docs/kv/`	`@elithrar`, `@thomasgauvin`, `@oxyjun`, `@cloudflare/product-owners`
`/src/content/docs/rules/`	`@pedrosousa`, `@cloudflare/appsec-reviewers`, `@elithrar`, `@smarsh-cf`, `@maurizioabba`, `@cloudflare/product-owners`
`/src/content/docs/workers/ci-cd/`	`@irvinebroque`, `@aninibread`, `@GregBrimble`, `@ericclemmons`, `@cloudflare/product-owners`, `@yomna-shousha`, `@MattieTK`, `@vy-ton`
`/src/content/docs/workers/`	`@cloudflare/workers-docs`, `@GregBrimble`, `@irvinebroque`, `@mikenomitch`, `@korinne`, `@WalshyDev`, `@cloudflare/deploy-config`, `@cloudflare/product-owners`, `@cloudflare/wrangler`, `@MattieTK`, `@cloudflare/dev-plat-leads`, `@vy-ton`
`/src/content/docs/workers/observability/`	`@irvinebroque`, `@mikenomitch`, `@nevikashah`, `@cloudflare/product-owners`, `@vy-ton`
`/src/content/docs/workers/static-assets`	`@irvinebroque`, `@GregBrimble`, `@WalshyDev`, `@cloudflare/deploy-config`, `@cloudflare/product-owners`, `@MattieTK`, `@vy-ton`
`/src/content/docs/workers/wrangler/`	`@cloudflare/wrangler`, `@irvinebroque`, `@cloudflare/product-owners`, `@MattieTK`, `@vy-ton`
`/src/content/partials/workers/`	`@cloudflare/workers-docs`, `@GregBrimble`, `@irvinebroque`, `@mikenomitch`, `@WalshyDev`, `@cloudflare/deploy-config`, `@cloudflare/product-owners`, `@cloudflare/wrangler`, `@MattieTK`, `@vy-ton`
`/src/content/release-notes/workers.yaml`	`@cloudflare/workers-docs`, `@GregBrimble`, `@WalshyDev`, `@aninibread`, `@cloudflare/deploy-config`, `@cloudflare/product-owners`, `@irvinebroque`, `@mikenomitch`, `@MattieTK`

github-actions · 2026-06-29T21:06:55Z

Preview URL: https://e097d9f6.preview.developers.cloudflare.com
Preview Branch URL: https://ajhawkings-restructure-versions-and-deployments.preview.developers.cloudflare.com

Files with changes (up to 15)

Bump order indicies for anything after versions & deployments

cloudflare-docs-bot · 2026-06-30T13:44:13Z

Review

✅ No issues found in commit e097d9f.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

_{No code review issues found.}

Conventions

Checks PR title, description, and redirect checklist.

_{No convention issues found.}

Style Guide Review

_{No style-guide issues found.}

Redirects

_{No missing redirect entries found.}

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
`/review`	Runs a review now. Incremental if a prior review exists, full if not.
`/full-review`	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
`/ignore-review-limit`	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
`/disable-auto-review`	Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run `/review` or `/full-review` manually.

ajhawkings · 2026-06-30T17:34:51Z

/review

dinasaur404 · 2026-07-02T14:06:00Z

/bonk please review and make any changes necessary

Co-authored-by: dinasaur404 <dinasaur404@users.noreply.github.com>

ask-bonk · 2026-07-02T14:10:24Z

Fixed the three style guide issues flagged by the bot review on PR #31787:

src/content/docs/workers/versions-and-deployments/deployment-management.mdx

Rewrote passive voice in the triggers note to active voice:
"To apply changes to a Worker's triggers ..., use the [wrangler triggers deploy] command."

src/content/changelog/workers/2025-09-11-increased-version-rollback-limit.mdx

Replaced "Learn more about" with "For more information, refer to".

src/content/changelog/workers/2025-02-03-workers-metrics-revamp.mdx

Replaced marketing language "This new interface enables you to:" with "With this new interface, you can:".

All CI validation checks pass (pnpm run check, pnpm run lint, pnpm run format:core:check).

github run

ajhawkings · 2026-07-02T14:21:38Z

wait don't think the changelog pages should be rewritten!

Preview URLs job is to link to a specific version, so I think this belongs here instead Also the old URL is /previews/ which could be confusing with the new Workers Previews. preview-urls is a better link

ajhawkings · 2026-07-02T16:42:47Z

/bonk review

ajhawkings · 2026-07-02T17:10:21Z

/full-review

ajhawkings added 2 commits June 29, 2026 11:46

[Workers] Move versions and deployments out of configuration

1f7d4e0

Relocate the versions and deployments pages from /workers/configuration/versions-and-deployments/ to /workers/versions-and-deployments/ and update all internal links and redirects accordingly.

github-actions Bot assigned dinasaur404 and irvinebroque Jun 29, 2026

github-actions Bot assigned th0m, danlapid, elithrar, iglesiasbrandon, joshthoward, lambrospetrou, Oxyjun and rita3ko Jun 29, 2026

ajhawkings added 4 commits June 30, 2026 10:56

Restructure version overrides and fix version affinity page & redirects

f78cbe7

Update sidebar order

8d258aa

Bump order indicies for anything after versions & deployments

Various fixes to links, clarity and grammar

96dd01d

Flag limits on which versions can be deployed more clearly

1b06cb5

ajhawkings marked this pull request as ready for review June 30, 2026 13:43

ajhawkings requested a review from irvinebroque as a code owner June 30, 2026 13:43

ajhawkings requested review from a team, Oxyjun, danlapid, elithrar, iglesiasbrandon, ivoryibu, joshthoward, lambrospetrou, rita3ko, sejoker, smarsh-cf, th0m and thomasgauvin as code owners June 30, 2026 13:43

Implement suggestions from code review

910ca4b

Fix 3 style guide issues from bot review

59a2d80

Co-authored-by: dinasaur404 <dinasaur404@users.noreply.github.com>

ajhawkings and others added 4 commits July 2, 2026 15:30

Revert changelog rewrites

90d47a9

Move preview URLs under versions section

ee9098d

Preview URLs job is to link to a specific version, so I think this belongs here instead Also the old URL is /previews/ which could be confusing with the new Workers Previews. preview-urls is a better link

Fix error in revert commit

11d9c84

Fix table formatting errors

e097d9f

ajhawkings requested a review from chythram05 July 2, 2026 17:34

chythram05 approved these changes Jul 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Workers] Restructure versions and deployments docs#31787

[Workers] Restructure versions and deployments docs#31787
ajhawkings wants to merge 12 commits into
productionfrom
ajhawkings/restructure-versions-and-deployments

ajhawkings commented Jun 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 29, 2026 •

edited

Loading

Uh oh!

cloudflare-docs-bot Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

ajhawkings commented Jun 30, 2026

Uh oh!

dinasaur404 commented Jul 2, 2026

Uh oh!

ask-bonk Bot commented Jul 2, 2026

Uh oh!

ajhawkings commented Jul 2, 2026

Uh oh!

ajhawkings commented Jul 2, 2026

Uh oh!

ajhawkings commented Jul 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

12 participants

Uh oh!

Conversation

ajhawkings commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Documentation checklist

Uh oh!

github-actions Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cloudflare-docs-bot Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review

Code Review

Conventions

Style Guide Review

Redirects

Uh oh!

ajhawkings commented Jun 30, 2026

Uh oh!

dinasaur404 commented Jul 2, 2026

Uh oh!

ask-bonk Bot commented Jul 2, 2026

Uh oh!

ajhawkings commented Jul 2, 2026

Uh oh!

ajhawkings commented Jul 2, 2026

Uh oh!

ajhawkings commented Jul 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

12 participants

ajhawkings commented Jun 29, 2026 •

edited

Loading

github-actions Bot commented Jun 29, 2026 •

edited

Loading

github-actions Bot commented Jun 29, 2026 •

edited

Loading

github-actions Bot commented Jun 29, 2026 •

edited

Loading

cloudflare-docs-bot Bot commented Jun 30, 2026 •

edited

Loading