Page MenuHomePhabricator

[Epic] Undeploying StructuredDiscussions (Flow)
Open, Needs TriagePublic


This work is in discussion and not currently prioritized by any WMF team. A community consultation will be started if plans are made to move this work forward.


Flow is a complex piece of software that was never quite finished, fits poorly into the MediaWiki architecture due to its many (eventually un-uitilized) layers of abstraction, lacks key features (such as search and solid moderation) and has many disruptive bugs, and is rejected by most Wikimedia communities. While there are communities that are happy with it, the value it provides isn't commensurate with its maintenance cost, much less with the expected future maintenance cost once there are major changes to Parsoid or VisualEditor. DiscussionTools now provides a similarly user-friendly UI, without all the problems. We should invest into undeploying Flow - it will be a significant effort, but keeping it in production would take more effort eventually.


Talk pages were long seen as a usability pain point (see the talk pages consultation's historical overview). The LiquidThreads extension was created back when the movement had very limited technical resources; plans to improve it eventually evolved into replacing it with an ambitious workflow system, Flow (later renamed StructuredDiscussions) which would have different modules for different types of talk page activities such as threaded discussion, voting or requests.

The eventual release only supported threaded discussion, and while it was a huge usability improvement for users unfamiliar with wikitext, it broke a number of workflows that power users considered very important, such as moderation or talk page refactoring. As a result, the rollout of Flow met fierce opposition from many wiki communities, and deployments were halted (and in some cases reversed). The WMF paused development in 2015 and instituted a freeze in new deployments of Flow a few years later. a few communities still use Flow.

In 2019, the WMF organized the talk pages consultation to look at the future of talk pages. The consultation yielded the Talk pages project. That project produced the DiscussionTools extension, which gained wide community adoption and is now the default on all wikis.

Community members have initiated discussions to replace Flow pages with DiscussionTools on and at


Maintenance burden

Maintaining Flow is a drain on WMF resources:

  • It is a large and complex codebase, with approximately 36,000 lines of code.
  • The code is complicated to reason about and difficult to work with. Some of the original authors are no longer at WMF.
  • As it provides an alternative talk page implementation, all features that need to be interact with talk pages need a separate Flow and wikitext implementation. On the frontend side this is somewhat managed via mw.messagePoster, on the server side there isn't an off-the-shelf way to do it.
  • Subtle bugs relating to database replication issues periodically cause user talk pages to become broken (see e.g. T308907). Someone from Growth then has to run a maintenance script to fix the problem. Fixing the underlying issue is not trivial.
  • Flow accounts for 25 open issues on the production error workboard. There have been 111 Flow production error tasks in total.
  • There are 16 open Flow tasks tagged with Security, including some crippling limitations to moderation functionality. The non-trivial data flow makes it nearly impossible to make sure proper escaping is done before building SQL queries, making it prone to SQL injection.
  • There are ~1200 open tasks on the Flow workboard, with about a hundred of them having high priority.
  • Other teams are blocked on overdue maintenance needed in Flow: Content Transformers needs stored Flow HTML to be updated to the newest Parsoid version (T209120, T124837). Given its shaky change list integration (see below), it will require a lot of extra work for patrolling or moderation changes (a priority area for the next year).
  • Flow uses patterns and libraries not found elsewhere in MediaWiki, increasing maintenance cost. For example, it uses Pimple rather than MediaWikiServices for dependency injection (T150350), and it uses lightncandy for its templates, unlike any other extension.
Architecture burden

Because Flow was intended to be very generic and support all kinds of different workflows, the codebase ended up with many layers of abstractions (which eventually weren't used since only one workflow was implemented), making it hard to understand and maintain. Because it envisioned sharing talk pages between multiple wikis (this mostly got implemented but wasn't deployed), it had to invent its own alternative revision system. In addition, its authors tried to innovate in directions that the wider MediaWiki community didn't pick up on (e.g. using MySQL as a noSQL database), so Flow ended up being something of an alien object wedged into MediaWiki. Not using the revision table means Flow has to reimplement every single feature related to changes lists (page history / contributions / RC / watchlist) and moderation that other extensions get for free.

UX burden

Two competing interfaces for the same use case, where the user cannot chose which one to use and eventually has to learn both (wikis that use Flow don't use it on all talk pages), adds to the mental burden of using the site. While at a high level Flow is in many ways closer to user expectations of how a discussion system should look, the implementation is unfinished, lacks key features (such as searching or legible links), has many severe bugs and usability issues (e.g. T324416) and integrates with moderation tools poorly.

Risk of emergency undeployment

Undeploying Flow would be a significant export and a lengthy project. However, if we don't expend that effort and then find ourselves in a situation where we need to undeploy Flow anyway and can't take several weeks to do it (e.g. a hard-to-fix security issue is found), the effects would be quite catastrophic. All Flow content and all Flow-related log entries and page histories would become inaccessible, Flow-related entries would disappear from user contributions. If Flow gets reenabled later, some of the content would be corrupted or lost (as Flow needs to keep its own database in sync with e.g. page moves).

See also

Related Objects

Event Timeline

KStoller-WMF renamed this task from [Epic] Prepare StructuredDiscussions undeployment to [Epic] Undeploying StructuredDiscussions (Flow).May 3 2023, 3:35 AM
KStoller-WMF updated the task description. (Show Details)
Tgr updated the task description. (Show Details)

Separately, I want to note that one of the cool features of StructuredDiscussions is that they allowed you to add new topics to the top, as in all standard forums. This has not yet been implemented in MediaWiki: T33919: Allow posting new sections to top of page on a per-page basis.