SCROLL/Docs/Guide

SCROLL process is an MVP. If something is unclear, missing, or wrong for your situation, please give feedback on the Slack channel #production-readiness-checklist

Scrolling to production: a starter guide for humans.

This page explains how a service moves from "we want to ship this" to "running in production with users", using the SCROLL (Service Checklist for Readiness, Operations, Launch and Lifecycle) process.

If you are about to start your first SCROLL, read this page end-to-end.

To see a fully worked example, visit SCROLL: worked examples. For quick answers to common questions, see the SCROLL FAQ.

Who is this for?

Developer teams shipping a new service, extension, or significant feature to Wikimedia production.
Program managers coordinating a launch across teams.
SRE Scroll Bearers reviewing readiness.

What is SCROLL?

SCROLL stands for Service Checklist for Readiness, Operations, Launch and Lifecycle. It is a flexible process for launching services to production with confidence and shared understanding across teams. A Scroll (lowercase) is a wiki page per service/component, structured as a checklist of items grouped into five sections:

Service summary
Operating procedures
Release confidence
Observability
Reliability and performance

Each item (a single row in a section's checklist, for example "Do you have a Wikitech page?") has a status, a priority, an owning team, and a sign-off. The page is the single shared artefact that the developer team, SRE, and other stakeholders work from.

Roles

Development Owner: Owns the component. Fills in most items, does most of the work, and requests review. See mw:Wikimedia Production/Service Catalog/Ownership Roles and Responsibilities#Ownership responsibilities for more details.
SRE Scroll Bearer: An SRE assigned as the reviewer and partner for this Scroll. Walks through the checklist with the team, scopes which items apply, reviews progress at each chapter, and signs off when ready.
Program manager: Coordinates target dates, keeps stakeholders aligned, and tracks milestones across teams. Not required for every Scroll, but useful for cross-team launches.
Other owning teams: Some items may be owned by Data Platform, Security, Traffic, etc. The Scroll Bearer helps identify them during scoping.

Before you begin

You will need:

A design describing what you are building and why. At a minimum it should cover: the problem and goals, a high-level architecture, technologies, and dependencies. The test is whether a Scroll Bearer can understand the component's shape and needs, not its length.
A parent Phabricator task (the Scroll epic, to create with the Phabricator form) to hang sub-tasks off.
A rough idea of your soft launch (rollout to some users) and full launch (rollout to all users) target dates.

You do not need everything ready before starting; that is what the SCROLL is for. But these are the inputs that let the Prologue happen.

SCROLL at a glance

Each SCROLL has a prologue and two chapters. The prologue is one-off scoping; chapters 1 and 2 are the actual work

Prologue: The Scoping

Goal: agree on what applies, who owns what, and when.

Developer team: Kick off a SCROLL process by creating a request in Phabricator, then create a new empty Scroll via the SCROLL landing page. This is to land in a tracked queue rather than than going through informal pings.
Developer team + Scroll Bearer: meet to walk through the checklist together.
- Mark which items apply and which can be skipped (including ❓ items that need scoping).
- Assign owning teams per item.
- Agree on soft launch (some users) and full launch (all users) target dates, as well as any milestone sync points in between.
- Loop in management on dates if needed.

Prologue closes when: the Scroll has owners assigned, scope agreed, and dates on the Service/Component identity card.

Chapter 1: The Soft Launch (rollout to some users)

🚀 Goal: ship to a subset of users, not everyone yet

Developer team: complete all 🚀 items they own.
SRE and other owning teams: complete their 🚀 items.
Scroll Bearer: review the Scroll and leave comments on items.
Developer team: address comments.
If blockers remain, developer team + Scroll Bearer meet to agree on revised dates.

Chapter 1 closes when: all 🚀 items signed off. Service is approved for soft launch traffic.

Chapter 2: The Full Launch (all users)

💯 Goal: ramp up to all users / full traffic. Everything is in place.

Developer team: complete all 💯 items they own.
SRE and other owning teams: complete their 💯 items.
Scroll Bearer: review and comment.
Developer team: address comments.
Developer team + Scroll Bearer: meet, perform SCROLL validation, or agree on revised dates if blockers remain.
Full traffic ramp-up, and sail into the sunset! ⛵

Chapter 2 closes when: all 💯 items signed off. Service is approved for all users.

The SCROLL lifecycle

Every Scroll carries a status banner at the top showing its state. The banner is set by a single parameter, which also files the page into the matching category, so the landing page can list Scrolls by stage (requested, active, finished).

The two middle stages, in progress and in review, are not one-off steps: a Scroll cycles between them within each chapter. The team completes a chapter's items (in progress), hands the chapter to the Scroll Bearer (in review), addresses comments, and repeats until the chapter closes, then the same cycle runs again for the next chapter.

Stage	What it means
📥 Requested	The page exists but scoping is not yet finished. The default for a new Scroll, until the Prologue closes.
🛠️ In progress	The team (with SRE and other owners) is working through the current chapter's items.
🔎 In review	The Scroll Bearer is reviewing the current chapter and the team is addressing comments, working towards closing it.
✅ Completed	Both chapters complete; the component is approved for all users.

Set whichever of in progress / in review reflects what is happening right now. There is no separate category to maintain: update the banner's parameter and the listing follows.

Navigating the checklist

Legend

You will see these symbols throughout the checklist. They are part of the SCROLL!

Status

🟢 done
🔴 not done
N/A

Priority

🚀 required for soft launch (rollout to some users).
💯 required for full launch (all users).
❓ needs scoping / may not be applicable. Decided during Prologue.

Required for (type of component)

⚙️ service (any new service in WikiKube, especially if interacting with MediaWiki)
🧩 extension (a new MediaWiki extension, especially if exposing new endpoints)
🌻 core feature (major reworks of MediaWiki internals, especially if exposing new endpoints or changing systems requirements)
✨ feature (a new complex feature that interacts with MediaWiki or its extensions, e.g HCaptcha)

The checklist columns

Each row in the checklist has the following columns.

: The item number, used to refer to the item in conversation or in comments.
Status: The current state of the item, rendered as 🟢 Done, 🔴 Not Done, or N/A. The marker is set via the status template; in VisualEditor the cell offers a drop-down of the three values. The person who signs off the item also flips its Status to 🟢 Done (see Signed off by below).
Priority: 🚀, 💯, or ❓, as in the legend above.
Required for: The type(s) of component the item applies to.
Item: The question or task the item asks.
Phab: Link to the Phabricator task that tracks the work for this item. Every item must be attached to a Phabricator task, hung off the SCROLL epic. Some items may be naturally grouped in the same task.
Remarks: Free-text answers or notes for an item: scope decisions, links to evidence, reasons something is not applicable. The greyed text you see in this column on a fresh SCROLL is guidance about what the item is asking for; replace it with your actual answer when applicable, or remove it if it does not apply.
Assignee: The person responsible to do this work. The greyed text you see in this column instructs if this is typically the developer team, SRE, or another team.
Signed off by: Person who has confirmed the item is complete and acceptable and flips Status to Done. Typically this is the Scroll Bearer, but for some items it may be another team (e.g. Traffic sign-off).
Date: The date the sign-off was given.

Shaping the process

SCROLL is meant to be useful, not bureaucratic.

Each Scroll is shaped by its component The checklist is a starting point. The Prologue decides which items apply, which are skipped, and which need scoping (❓). Not every component needs every item, and not every item needs the same depth of work.
The process itself is a work in progress. SCROLL is new, and we expect to adjust it as we learn what works and what does not. If an item feels redundant, a section is missing, a column is doing the wrong thing for your component, or the chapter structure does not fit your launch, say so in the #production-readiness-checklist channel. We will discuss and update the process as needed.

Tips

Start your SCROLL early. The Prologue is most useful when there is still time to influence the design.
Treat dates as commitments, not wishes. If they slip, communicate.
Use the Remarks column. The Scroll is a record. If an item is skipped, it should be recorded as to why.
One SCROLL per component. If you are launching several related components, each gets its own Scroll; however, this is subject to discussion during the Prologue.
Not every component needs a SCROLL process! However, a discussion with the SRE team is recommended to confirm this.
When in doubt, ask your Scroll Bearer. They are your partner for the whole process, not just a gatekeeper at sign-off. Use them to scope items, settle "does this apply to us?" questions, and find the right team when an item is owned elsewhere.

Questions or help

Please refer to FAQ for common questions.If something is unclear, missing, or wrong for your situation, please give feedback on the Slack channel