Page MenuHomePhabricator

Document a MediaWiki quickstart workflow for contributors
Closed, ResolvedPublic


Lead: apaskulin
Advising: Krinkle


  • Evaluate whether an easy-to-use, container-free, quickstart workflow for setting up a local MediaWiki development environment makes it easier to get started contributing to MediaWiki. See the Project outcomes section.
  • If the new quickstart workflow meets the success criteria, integrate it with the MediaWiki development environment docs.
  • Collect information and feedback that can be used to improve all MediaWiki development environments. See the Project outcomes section.


As of October 2023, the fastest way to set up a development environment for MediaWiki is to use Docker. However, for people who aren't familiar with Docker, using containers for a development environment adds complexity and can be a barrier to entry. For more background information, see T347347: Make "Quick" MW install a thing.


This project contributes to Wikimedia Foundation 2023-24 annual plan objective WE3: "Increase collaboration and efficiency among software developers by improving the development process for MediaWiki", specifically key result WE 3.2: "Increase by 20% the number of authors that have committed more than 5 patches across a specific set of MediaWiki repositories that are deployed to production." This project is tracked as hypothesis WE3.2.4.

Success criteria

1. Setup time
The new workflow should be quick to set up. We'll evaluate setup time by testing the workflow on Windows, Mac, and Linux.

2. Complexity
The new workflow should be less complex than a container-based workflow. While it's difficult to measure complexity, in this case we'll use the number of actions required to complete the setup. Since the number of steps can vary based on how the document groups them, using actions helps us focus on the concepts instead of the presentation.

3. Ease of use
The new workflow should be easy to set up and use. We'll measure this qualitatively by collecting feedback from contributors.


This project is focused on new contributors, less experienced contributors, and contributors with simple use cases. It does not address needs for development environments that reproduce Wikimedia production, require multiple wikis, or use uncommon extensions or skins.


  • WMF MediaWiki Engineering team
  • WMF API Platform team
  • WMF Technical Documentation team
  • WMF MediaWiki Product
  • MediaWiki developers (staff, affiliate, and volunteer)
  • MediaWiki documentation contributors
  • MediaWiki Stakeholders' Group

Project plan

  • 1. Research and prep
  • 2. Test new workflow
    • with stakeholders
    • with new contributors
    • at the WMF MediaWiki Code Jam (December 2023)
  • 3. Publish finding and recommendations. See the Project outcomes section.

Project outcomes

Project goal: Evaluate quickstart workflow

Evaluate whether an easy-to-use, container-free, quickstart workflow for setting up a local MediaWiki development environment makes it easier to get started contributing to MediaWiki compared to MediaWiki-Docker.

I measured ease of getting started through:

  1. Setup time
  2. Complexity
  3. Ease of use (qualitative feedback)
1. Setup time

The local quickstart is approximately 30% faster to set up than MediaWiki-Docker, making the local quickstart the quickest documented way to set up a local development environment for MediaWiki.


To measure setup time, I started from a state in which:

  • git is installed
  • a package manager is installed (such as Homebrew on Mac)
  • available packages have been updated (such as via apt update)

The end state must have a local MediaWiki instance open in a browser with Vector enabled. These tests did not include setting up a developer account or SSH key.

Through testing on my WMF Mac laptop, I established a baseline for MediaWiki-Docker of 10 minutes. The MediaWiki-Docker docs give an estimated setup time of 15 minutes, but I decided to use the shorter time that I observed in my tests.

I tested the local quickstart using my WMF Mac laptop, a personal Windows laptop, and virtual Linux machines set up using Vagrant. I also conducted two user tests (one on Mac and one on Linux) with users who had never used a MediaWiki development environment before. The average results, rounded up to the nearest minute, were 7 minutes on Mac, 6 minutes on Linux, and 6 minutes on Windows.

2. Complexity

Compared with MediaWiki-Docker, the local quickstart is less complex, requiring approximately 40% fewer action to complete. The quickstart removes the need to edit files as part of the setup process and provides a single place to run commands that interact with MediaWiki, in contrast to the need to run some commands inside the MediaWiki container when using MediaWiki-Docker.


It's difficult to measure complexity, so, in this case, I used the number of actions required to complete the workflow using the same start and end states as the setup-time measurement. Since the number of steps can vary based on how the document groups them, using actions helps us focus on the concepts instead of the presentation.

Based on the documentation, MediaWiki-Docker requires 9 actions:

  1. Install Docker.
  2. Clone MediaWiki.
  3. Create .env file.
  4. Add user ID and group ID to your .env file.
  5. Start containers.
  6. Install PHP dependencies.
  7. Install MediaWiki. (On Windows, this is two actions.)
  8. Clone Vector.
  9. Enable Vector in LocalSettings.php

The local quickstart requires 5 actions:

  1. Install PHP and Composer. (On Windows and Ubuntu 20, this is two actions.)
  2. Clone MediaWiki and Vector.
  3. Install PHP dependencies.
  4. Install MediaWiki.
  5. Start server.
3. Ease of use

The quickstart received positive feedback from 2 users in user tests, 2 users through comments on and Phabricator, and 6 users surveyed following the WMF MediaWiki CodeJam. The wiki page on has received 744 pageviews (ref) since first published in October 2023.


Feedback highlights:

  • "This is looking REALLY good. Very readable." - from
  • "Too bad I didn't know this when I was getting started with MediaWiki." - from Phabricator

CodeJam survey:

Out of 54 participants, there were 16 responses to the survey. Of these 16 responders, only 3 reported setting up a new development environment; the other 13 used an existing development environment. Of the 3 responders who set up a new development environment (all of which submitted a patch as part of CodeJam), 2 chose the local quickstart, and 1 chose Docker/MediaWiki CLI. Of the 13 responders who used an existing environment, 4 used the quickstart, compared with 7 who used MediaWiki CLI or Docker, 1 who used Vagrant, and 1 who used custom scripts. All 6 responders who used the local quickstart reported being satisfied with the tooling and the documentation.

Project goal: Integrate the new docs

If the new quickstart workflow meets the success criteria, integrate it with the MediaWiki development environment docs.

I concluded that there was enough improvement in the success criteria to justify replacing the local installation section on How to become a MediaWiki Hacker with a link to the local quickstart.

Project goal: Collect information and feedback

Collect information and feedback that can be used to improve all MediaWiki development environments.


Because MediaWiki-Docker is used in in the MediaWiki core repository, it is considered the default development environment for MediaWiki. The reach of is likely the reason why the MediaWiki-Docker wiki page has significantly more pageviews than other development environment pages or than the landing page that links to it.

Overall, I found MediaWiki-Docker quick and easy to set up using Docker Desktop on Mac. In the default configuration, MediaWiki-Docker offers similar functionality to the local quickstart, using SQLite and the standard process for installing extensions. These features work well for simple use cases, but don't support more complete needs like running multiple wikis. Further investigation into these complex use cases is needed to make recommendations about how to evolve current development environments to support them.

Short-term documentation improvements to the MediaWiki-Docker quickstart in

  1. Fix formatting errors and simplify language.
  2. Improve the end state of the quickstart by including installing and enabling Vector, so that the quickstart process ends with a local MediaWiki instance you can interact with, instead of ending with the skin-not-found error page. This will reduce the number of actions in the MediaWiki-Docker workflow from 9 to 7.
  3. Simplify step 3. Prepare .env file to two echo commands, one for Windows and one for Linux/Mac. If possible, move the Xdebug step to the Xdebug section. This will further reduce the number of actions in the MediaWiki-Docker workflow by one.
  4. Add link to Local development quickstart as a container-free option.

Long-term documentation considerations:

  1. Should the documentation in be moved to where it can be translated and more easily edited? This should be part of a decision that also considers the documentation in the /docs directory.
  2. The extension-specific subpages of MediaWiki-Docker (such as MediaWiki-Docker/Extension/Echo) partially duplicate and are siloed from the primary extension documentation pages. How can this duplication be reduced and these two sets of pages more easily maintained together?
MediaWiki CLI

MediaWiki CLI's setup wizard provides a great user experience that could theoretically be expanded to offer many different types of development environments. However, maintaining a tool like MediaWiki CLI is more complex than a docker-compose file or a set of composer commands. Further investigation is required to assess the maintainability of MediaWiki CLI and evaluate whether it can become a replacement for MediaWiki-Docker.

Event Timeline

I've started putting together the quickstart instructions in a sandbox page. So far I've tested it on Mac, Ubuntu, Debian, and Fedora. I'll be adding Windows next week. Some highlights:

  • We decided not to support Ubuntu versions earlier than 20, as is in line with the MediaWiki PHP support policy.
  • I've decided to include installing Vector in the end state we're targeting. This makes for a better experience since the setup process ends with a MediaWiki instance you can interact with in the browser.
  • By cloning core and Vector before running the install script, we're able to skip the step later on to enable Vector by editing LocalSettings.php. This also works with MediaWiki Docker, so we could use the same process there.

@Krinkle, the quickstart doc is ready for your review. Feel free to leave comments here or on the talk page.

@apaskulin I'm done with my review of

In terms of "important" things that stood out:

  • I updated the list of required PHP packages to omit legacy aliases that are built-in nowadays (such as "php-dom"), and add some recommended packages (like "php-apcu" and "php-curl"). Detailed reasoning in the edit history of, which I've updated at the same time.
  • Combined core and Vector clone into one command.

We already spoke since we made those changes, I'm only mentioning it again here for transparancy.

Beyond that, I made a few bold tweaks just now, but nothing that I feel strongly about. Feel free to undo or revise as you see fit:

  • Reduce clone instruction to only an HTTPS variant. Leaving it to the Developer account and Gerrit setup to automatically change that to an SSH remote if/when needed. I've updated the Gerrit Tutorial and Gerrit TLDR accordingly.
  • Apply "ContentGrid" for the first step to give it a stronger feeling of being a single step where you choose one box. Makes the page notably shorter as well, and makes long text in this section stand out as cram (thus discouring long text from being added here, hopefully).
  • Implement "Copy to clipboard" functionality and add it to various boxes.

Thanks, @Krinkle! This is great feedback, and the "Copy to clipboard" functionality is awesome! I've made a few final edits (including adding a note about the default admin credentials), and moved the page to mw:Local development quickstart. For next steps, I'll be requesting broader feedback on the parent task and the Village Pump.

I'll be requesting broader feedback on the parent task and the Village Pump.

This is now done both on wiki and T347347#9351046.

Huge thanks to everyone who left feedback on the talk page, edited the guide, and submitted patches to improve the tooling! The initial results of the CodeJam survey show that several participants used a local installation for their development environment (5 participants using a local installation versus 7 using Docker) and that they were generally satisfied with it (averaging 4 out of 5).

Based on this, I've removed the experimental banner from the guide and update the local installation section of How to become a MediaWiki hacker to point to it. I'm planning to share a final report of the findings of the survey and other sources of feedback in January before closing this task.

This work is now complete! See the task description for final metrics and recommendations. A big thanks to everyone who contributed and provided feedback. The quickstart guide can continue to evolve from here using the standard on-wiki process.

Change 992164 had a related patch set uploaded (by Ladsgroup; author: Amir Sarabadani):

[mediawiki/core@master] docs: Link to "Local development quickstart" in README

Change 992164 merged by jenkins-bot:

[mediawiki/core@master] docs: Link to "Local development quickstart" in README