> For the complete documentation index, see [llms.txt](https://engineering.umh.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engineering.umh.app/engineering/development-process/how-to-build/tickets/rollout.md). # Rollout What goes into a rollout ticket, and the template to copy. Owner: Jeremy **A rollout ticket's description says what we want to be true after the rollout and how we will measure it.** Each [rollout ticket](/engineering/development-process/how-to-decide-what-to-build.md#rollout-tickets) starts as a pitch. ## Rules * The title starts with `[ROLLOUT]`. * A rollout ticket starts as a pitch: the problem, what we are shipping and what we are not shipping. * Before the bet, it adds the spec and the plan for running the feature for the next years. * The Code Owners and the Product Owners sign off before the bet and again before the flag goes on by default. ## The pitch **The pitch brings up problems before anyone writes code.** Before we wrote pitches, these came up only in code review: whether to build something at all, technical questions such as Sentry, docs and feature flags, a product concern, a conflict with a vision, or work more complex than anyone thought. **When you write the pitch, copy the** [**template**](#template) **into the ticket's description.** The pitch is its first part, and it has the first three parts of the [PR template](https://github.com/united-manufacturing-hub/united-manufacturing-hub/blob/staging/.github/PULL_REQUEST_TEMPLATE.md). Before you pitch, think about how you will own the feature for the next years: its [monitoring ticket](/engineering/development-process/how-to-build/tickets/monitoring.md), its alerts and its stability targets. A short problem statement that everyone understands, sales included, is harder to write than a long one. ### The breadboard **The breadboard lets everyone check whether the user journey is going to work.** Draw it in Excalidraw and link it from the pitch. As [Shape Up](https://basecamp.com/shapeup/1.3-chapter-04#breadboarding) puts it, a breadboard "has all the components and wiring of a real device but no industrial design." Show every step of the user journey: the screens a [user](/product/who-we-build-for.md#our-users) goes through, what they can act on there, and how one leads to the next. Do not draw a detailed mockup or vibe-code a prototype, for example with Lovable or klaus. Both lead to unnecessary discussions about design. ## Spec and plan **Before the bet, fill in the rest of the template: the spec, the threat model and the plan for running the feature.** [The security coding standard](/engineering/development-process/how-to-build/coding-standards/architecture/security.md#threat-model) says when a threat model is needed and what goes in it. **The description holds only what stays true.** What you see when you check the targets, and what is still missing, go into comments on the ticket and into the [product meeting](/culture/our-week.md#product-meeting). If a target changes, edit the description and say so in the product meeting. ## Header and sign-offs **The two sign-offs cover different things.** Before the bet, the [Code Owners](/engineering/product-engineer/code-owner.md) confirm the spec, including whether it is a [one-way door](/engineering/development-process/how-to-build.md#before-you-write-code). The [Product Owners](/engineering/product-engineer/product-owner.md) of the [user journeys](/engineering/product-engineer.md) it touches confirm that the problem fits the journey and its [visions](/engineering/development-process/how-to-decide-what-to-build.md#visions). Once [Stage 2](/engineering/development-process/how-to-ship.md#stages-and-the-feature-flag) is done, the [Value Engineers](/culture/working-with-the-rest-of-umh.md#value-engineer) can turn the flag on for single customers without further sign-offs. Before the flag goes on by default in Stage 3, the Code Owners and the Product Owners sign off what was built, including the wording users see. **The Features line names the** [**feature tags**](/engineering/development-process/how-to-build/coding-standards/architecture/error-management.md#feature-tags) **the ticket owns.** A Sentry issue with one of these tags becomes a sub-ticket of this ticket. We name tags rather than code paths. Nobody has to update a tag when the code moves. ## What we are shipping **This part names the change the way users will see it and gives its** [**changelog**](/engineering/development-process/how-to-ship/changelog.md) **sections: Preview while the flag is off by default, then the section it joins.** Use the [name customers and our documentation use](/engineering/development-process/how-to-build/tickets.md#public-names). ## Success **The targets cover stability, adoption and impact, once for during the rollout and once for after it.** The targets for during the rollout apply until the flag is removed from the code. The targets for after the rollout apply for as long as the feature ships. Each target says enough that someone can check it without asking you. The targets count enterprise customers with a license. We use community users' numbers as early warning signals or as extra evidence. We act on something community users hit when we expect it to happen at customers too. **Stability** needs a number: how many errors and warnings this feature is allowed to have. The errors that count are the ones whose [`feature` tag](/engineering/development-process/how-to-build/coding-standards/architecture/error-management.md#feature-tags) is on the Features line. During the rollout we check the number in the last weeks before we remove the flag, for example no new error in Sentry in the two weeks before removal. After the rollout the number stays, and the [monitoring ticket](/engineering/development-process/how-to-build/tickets/monitoring.md) takes it over once the rollout ticket is done. **Adoption** needs a number where telemetry can give one, and [product analytics](/engineering/development-process/how-to-decide-what-to-build/signals/product-analytics.md) is where that number comes from. Ideally, telemetry tells us which customer did what. Even when the goal is that one customer uses the feature, build in telemetry that confirms it. Where that is not possible, a Value Engineer's report in the ticket counts. After the rollout, the adoption on the day the flag is removed becomes the baseline. Adoption that keeps falling below that baseline counts as a missed target. **Impact** can be measured by a named person's report in the ticket. Every target needs its measure before the flag goes on for the first customer. A target based on a person's report needs no measure. ## Dashboard **Each rollout ticket gets one PostHog dashboard.** It is named `Rollout: (ENG-xxxx)` and linked under Success. It holds one insight per target. Each insight is named `ENG-xxxx : `, for example `ENG-5132 Adoption: customers still seeing the CPU status jump`. Tag every insight with the ticket ID in lowercase, for example `eng-5132`. Each target links the insight that decides it. A target measured in Sentry links a saved search instead. The dashboard stays after the ticket is done. The targets for after the rollout are read from it. Some rollouts can't be measured in PostHog, for example when the adoption happens on the developer side. Then the Product Engineer writes "Not needed" and the reason instead of the link. **A ticket can also link the dashboards of features built on top of it.** Its adoption can be counted from its sub-tickets. This helps a monitoring ticket whose own feature sends no telemetry. ## Stages and evidence **A person ticks each** [**stage**](/engineering/development-process/how-to-ship.md#stages-and-the-feature-flag) **box to record their decision.** The success targets have no boxes. Whether a target is met goes into comments. **Every ticked box and every comment that says a target is met links evidence that someone else can check, such as the insight, the Sentry search or a screenshot.** Blockers are sub-tickets. Bugs, tech debt and security issues sit under their [sub-tickets](/engineering/development-process/how-to-build/tickets.md). Don't list them in the description. Design docs, specs, the [threat model](/engineering/development-process/how-to-build/coding-standards/architecture/security.md#threat-model) and similar documents go on the ticket as Linear documents. Upload them as markdown. ## The ticket state **A rollout ticket's** [**state**](/engineering/development-process/how-to-build/tickets.md#the-ticket-state) **says only whether it was accepted.** It may still move to In Progress, In Review or Merged when someone links a pull request to it, and those three mean nothing here. {% hint style="info" %} **Tip:** never link a pull request or a commit to a rollout ticket. A linked pull request moves the ticket's state by itself. When the pull request is released, the release can close the ticket as well. {% endhint %} ## Template ```markdown **Owner:** **Appetite:** **Sign-offs:** Code Owners: · Product Owners: **Features:** **Spec:** **Threat model:** **Monitoring ticket:** ## Problem ## What we are shipping **Name:** **Changelog sections:** Preview, then when the flag goes on by default Previously <…>. Now <…>. **Breadboard:** **Feature flag:** · · default ## What we are NOT shipping - · · ## Success **Dashboard:** ### During the rollout (until the flag is removed from the code) - **Stability:** · counted: · who: · window: · does not count: <…> · - **Adoption:** - **Impact:** ### After the rollout (as long as the feature ships) - **Stability:** - **Adoption:** baseline = adoption on the day the flag is removed · - **Impact:** ## Discoverability **Changelog entries:** **Docs page:** **In the UI:** **Example:** ## Rollout **Customers:** · week · aligned with - [ ] Stage 1: in production with the flag off, released in - [ ] Stage 2: discoverability ready · telemetry and error reporting live · tested with the flag on by the Value Engineer and the Product Engineer · blockers resolved · plan to roll back · every target has its measure - [ ] Stage 3: flag on by default · Product Owners and Code Owners signed off · CTO approved · all hands demo: - [ ] Stage 4: targets for during the rollout met, or the miss accepted in a comment · no customer still switches back · flag removed from the code ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://engineering.umh.app/engineering/development-process/how-to-build/tickets/rollout.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.