Skip to content

docs: explain how to schedule a gradual rollout - #20036

Draft
phillram wants to merge 4 commits into
masterfrom
posthog/docs-scheduled-gradual-rollout
Draft

phillram wants to merge 4 commits into
masterfrom
posthog/docs-scheduled-gradual-rollout

Conversation

@phillram

@phillram phillram commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Changes

A user tried to build a 25% → 50% → 100% rollout with the Schedule tab and asked whether it works, since the docs say conditions are appended. They read that as "the first, lowest condition always wins". It does not: all condition sets are evaluated, a pass on any one is a pass, and rollout buckets are shared across sets, so the widest condition decides the result and nobody loses access mid-ramp.

The page already promises this in its intro ("roll it out to 100% of the users in 2 weeks") but never says how to get there. This adds a short Gradual rollouts section covering the ramp and its limits, plus a cross-link from the Add condition step.

Two paragraphs, one file, prose only. No screenshots: nothing visual changes.

Checklist

  • I've read the docs and/or content style guides.
  • Words are spelled using American English
  • Use relative URLs for internal links
  • I've checked the pages added or changed in the Vercel preview build
  • If I moved a page, I added a redirect in vercel.json — n/a, no page moved

pnpm format does not cover .mdx, so it makes no change here. The Vercel preview box is unchecked because the preview builds from this PR; the two anchors it links to were verified against the headings in creating-feature-flags.mdx.


Created with PostHog Desktop

The scheduled flag changes page promises a ramp to 100% in its intro, but it never explains how Add condition gets you there. It says only that conditions are appended, which reads as "the first, lowest condition always wins".

Add a section that shows the 25/50/100 schedule, states that a pass on any condition set is a pass, and lists the three limits: it only ramps up, the old conditions need deleting, and early exit breaks it.

Generated-By: PostHog Desktop
Task-Id: 3a5a2bd1-97b8-4a04-a498-2c229d834bba
@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Deploy preview

Status Details Updated (UTC)
🟢 Ready View preview Sep 09, 2026 07:52PM

@github-actions github-actions Bot added docs Improvements or additions to product documentation, "Docs" content PR only touches files under contents/ labels Sep 9, 2026
@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Vale prose linter → found 2 errors, 4 warnings, 0 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

contents/docs/feature-flags/scheduled-flag-changes.mdx — 2 errors, 4 warnings, 0 suggestions
Line Severity Message Rule
13:54 warning Use 'PostHog' instead of 'posthog'. Vale.Terms
15:54 warning Use 'PostHog' instead of 'posthog'. Vale.Terms
87:50 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
87:86 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
137:15 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
141:21 warning 'unexecuted' is a possible misspelling. PostHogBase.Spelling

@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

8.86 MiB (no change)

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint Eager size Budget Modules
app 18.46 MiB (+0.1 KiB / +0.0%) report-only 2054
Largest modules in the app closure
Module Size
./src/data/mcp-tools.json 1116.6 KiB
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css 761.1 KiB
./src/components/Stickers/Stickers.tsx 696.4 KiB
./node_modules/.pnpm/@radix-ui+react-icons@1.3.2_react@18.3.1/node_modules/@radix-ui/react-icons/dist/react-icons.esm.js 481.4 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/x-ray.mjs 480.8 KiB
./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules 395.1 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/im-the-driver.mjs 385.7 KiB
./src/hooks/useCustomers.tsx + 55 modules 370.0 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js 354.8 KiB
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules 351.4 KiB
./src/components/ProductComparisonTable/index.tsx + 126 modules 302.5 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js 281.9 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/doll-house.mjs 281.7 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/director.mjs 275.6 KiB
./src/components/SearchUI/index.tsx + 87 modules 273.0 KiB

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).

Drop the phase table and the bulleted limits. The table restated the prose, and each bullet carried one line of content. Two paragraphs say the same thing.

Generated-By: PostHog Desktop
Task-Id: 3a5a2bd1-97b8-4a04-a498-2c229d834bba
"The highest percentage decides the result" reads two wrong ways: that the scheduled change raises the number on the existing condition, and that the percentage picks the value the flag returns. Neither happens. State the mechanism instead: each change adds a condition, and the flag is on for anyone who passes at least one.

Also note that the phases need matching property filters, since a user only ramps across the conditions they qualify for.

Generated-By: PostHog Desktop
Task-Id: 3a5a2bd1-97b8-4a04-a498-2c229d834bba
"Everyone in the 25% bucket is also in the 50% bucket" leaves the obvious next question open: does a 25% condition plus a 50% condition reach 75%? It reaches 50%, because both conditions read the same bucket number and the sets overlap completely. Say so.

Generated-By: PostHog Desktop
Task-Id: 3a5a2bd1-97b8-4a04-a498-2c229d834bba
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

content PR only touches files under contents/ docs Improvements or additions to product documentation, "Docs"

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant