SCROLL/Docs/FAQ

Short answers to questions that come up about SCROLL.

For the full picture, start with the SCROLL guide
For what a finished SCROLL looks like, see the worked examples.

If your question is not answered here, please ask in Slack channel, so we can add it.

General

The checklist looks long, won't it add a lot of overhead for development?

Most items in a Scroll are not new work. This is work engineers would do anyway (metrics, smoke tests, dashboards, CI, resource management, storage needs), surfaced early when it is cheap rather than discovered mid-incident when it is expensive. The checklist mostly collects what should already exist and rarely invent work.

It may be also scoped down, as it is not a fixed list of items for everyone:

The Prologue, run with your Scroll Bearer, marks which items apply and which are skipped. Not every component needs every item, and some do not need a Scroll at all. But we believe they all deserve a SCROLL evaluation with your Scroll Bearer.
The checklist is filtered to soft-launch (🚀) and full-launch (💯) items, as well as between Service, Extension, Core Feature and Feature (see SCROLL Legend). For your case it's likely that you won't have to fill all item.
The Scroll Bearer is a partner who helps you cut scope, not a gate that adds it.

The aim is a usable operational artefact that both your team and SRE benefit from.

My project has different phases than Soft Launch and Full Launch

There’s no one size fits all given the diversity of project structures across P&T: some project require several experiments with different objectives while others can go faster to impact all users. SCROLL is providing a generic Soft launch/Full launch framework, which approaches things from a production impact perspective: what matters is how many users, how much traffic, how much supporting resources and dependencies... are impacted by the major phases of your project.

The mapping between your project phases and this framework is a great discussion to have at Prologue time with your Scroll bearer.

Process and scope

My extension already has a page on mediawiki.org, does it also need its own Wikitech page (item 1.1)?

Not always. The two wikis cover different things:

mediawiki.org documents the software
- what the extension does, configuration, usage
- repos, versions, parameters, user-facing documentation
Wikitech is the operational home
- its place in the MediaWiki architecture
- deployment, runbook, monitoring
- where most of sections 2 to 5 of a Scroll live

So item 1.1 is really asking "where do the operational details live?". How much you need is flexible, and you scope it with your Scroll Bearer during the Prologue:

An extension with production infrastructure (e.g. a standalone microservice) usually needs both a Wikitech page and a mediawiki.org page, with little to no duplication. The mediawiki.org page is for users, the Wikitech page is for operators.
A lightweight extension with little or no dedicated infrastructure may just need a redirect to the mediawiki.org page.

The point is that the operational information is findable from Wikitech. No one wants to maintain two full pages with the same content.

What does "Has the design been reviewed by SRE?" require? If the component is simple, or just reorganizes existing code, should this be N/A?

If an SRE (by default, the Scroll Bearer) has looked the service over and determined that it's simple, that counts as an SRE review and it can be marked Done. If they saw something that made them want to look closer or ask more questions, the review might take longer. The depth of the review will depend on the complexity of the service, but as long as the SRE Scroll Bearer is satisfied that they've reviewed sufficiently, the review is done.

Do MediaWiki extensions need an SLO (items 4.3 and 4.4)?

It depends on the extension. Some extensions have user-visible behavior, and we would want to fix it if it stopped working; those should be measured with an SLO. Other extensions don't, and in some cases an SLO may not be appropriate. Those items do have the 🧩 symbol ("required for extensions") because some extensions will need it.

Roles and sign-off

If the developer team marks an item N/A, does it still need a sign-off?

"N/A" can be a judgement call sometimes. It's best for the SRE Scroll bearer to review that decision and say "agreed, that doesn't apply here," and they should sign off to document that agreement.

It also makes it easy to look down the sign-off column and identify the unsigned items that still need attention.

← Back to SCROLL home · SCROLL guide