⚓ T348899 Document a MediaWiki quickstart workflow for contributors

⚓ T348899 Document a MediaWiki quickstart workflow for contributors
Page Menu
Phabricator
Create Task
Maniphest
T348899
Document a MediaWiki quickstart workflow for contributors
Closed, Resolved
Public
Actions
Edit Task
Edit Related Tasks...
Create Subtask
Edit Parent Tasks
Edit Subtasks
Merge Duplicates In
Close As Duplicate
Edit Related Objects...
Edit Commits
Edit Mocks
Mute Notifications
Protect as security issue
Assigned To
apaskulin
Authored By
apaskulin
Oct 13 2023, 9:41 PM
2023-10-13 21:41:38 (UTC+0)
Tags
Tech-Docs-Team
(Done)
MediaWiki-Documentation
MW-1.42-notes (1.42.0-wmf.15; 2024-01-23)
Referenced Files
None
Subscribers
Aklapper
apaskulin
Bmueller
Frostly
KBach
kostajh
Krinkle
Ladsgroup
Description
Lead: apaskulin
Advising: Krinkle
Goals
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.
Background
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 "Quickstart" MW install a thing
Priority
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.
Scope
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.
Stakeholders
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
Prepare a wiki page documenting the new workflow to use in testing
Draft
Review
Finalize
Document and test existing workflows
Decide on start and end states for success criteria
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.
Either deprecate or integrate the new workflow with the
MediaWiki development environment docs
Evaluate the limitations of new and existing workflows. 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:
Setup time
Complexity
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.
Details
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.
Details
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:
Install Docker.
Clone MediaWiki.
Create .env file.
Add user ID and group ID to your .env file.
Start containers.
Install PHP dependencies.
Install MediaWiki. (On Windows, this is two actions.)
Clone Vector.
Enable Vector in LocalSettings.php
The local quickstart requires 5 actions:
Install PHP and Composer. (On Windows and Ubuntu 20, this is two actions.)
Clone MediaWiki and Vector.
Install PHP dependencies.
Install MediaWiki.
Start server.
3. Ease of use
The quickstart received positive feedback from 2 users in user tests, 2 users through comments on MediaWiki.org and Phabricator, and 6 users surveyed following the WMF MediaWiki CodeJam. The wiki page on MediaWiki.org has received 744 pageviews (
ref
) since first published in October 2023.
Details
Feedback highlights:
"This is looking REALLY good. Very readable." - from
MediaWiki.org
"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.
MediaWiki-Docker
Because MediaWiki-Docker is used in DEVELOPERS.md in the MediaWiki core repository, it is considered the default development environment for MediaWiki. The reach of DEVELOPERS.md 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 DEVELOPERS.md:
Fix formatting errors and simplify language.
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.
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.
Add link to Local development quickstart as a container-free option.
Long-term documentation considerations:
Should the documentation in DEVELOPERS.md be moved to MediaWiki.org 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.
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.
Details
Related Changes in Gerrit:
Subject
Repo
Branch
Lines +/-
docs: Link to "Local development quickstart" in README
mediawiki/core
master
+2
-0
Customize query in gerrit
Related Objects
Search...
Task Graph
Mentions
Status
Subtype
Assigned
Task
Resolved
Krinkle
T347347
Make "Quickstart" MW install a thing
Resolved
apaskulin
T348899
Document a MediaWiki quickstart workflow for contributors
Resolved
BUG REPORT
apaskulin
T350522
MediaWiki install command sets wgScriptPath incorrectly on Windows
Mentioned In
T347347: Make "Quickstart" MW install a thing
Mentioned Here
T347347: Make "Quickstart" MW install a thing
Event Timeline
apaskulin
created this task.
Oct 13 2023, 9:41 PM
2023-10-13 21:41:38 (UTC+0)
Restricted Application
added a subscriber:
Aklapper
View Herald Transcript
Oct 13 2023, 9:41 PM
2023-10-13 21:41:39 (UTC+0)
apaskulin
added a parent task:
T347347: Make "Quickstart" MW install a thing
Oct 13 2023, 9:41 PM
2023-10-13 21:41:57 (UTC+0)
apaskulin
moved this task from
Backlog
to
Active projects
on the
Tech-Docs-Team
board.
Frostly
subscribed.
Oct 15 2023, 4:21 AM
2023-10-15 04:21:47 (UTC+0)
kostajh
subscribed.
Oct 16 2023, 7:55 AM
2023-10-16 07:55:00 (UTC+0)
KBach
subscribed.
Oct 16 2023, 8:17 AM
2023-10-16 08:17:03 (UTC+0)
Ladsgroup
subscribed.
Oct 16 2023, 6:23 PM
2023-10-16 18:23:23 (UTC+0)
apaskulin
updated the task description.
(Show Details)
Oct 17 2023, 12:20 AM
2023-10-17 00:20:11 (UTC+0)
apaskulin
updated the task description.
(Show Details)
Oct 27 2023, 11:54 PM
2023-10-27 23:54:47 (UTC+0)
apaskulin
added a comment.
Oct 27 2023, 11:57 PM
2023-10-27 23:57:17 (UTC+0)
Comment Actions
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.
apaskulin
added a subtask:
T350522: MediaWiki install command sets wgScriptPath incorrectly on Windows
Nov 4 2023, 1:29 AM
2023-11-04 01:29:10 (UTC+0)
apaskulin
closed subtask
T350522: MediaWiki install command sets wgScriptPath incorrectly on Windows
as
Resolved
Nov 8 2023, 8:51 PM
2023-11-08 20:51:58 (UTC+0)
apaskulin
updated the task description.
(Show Details)
Nov 10 2023, 6:15 PM
2023-11-10 18:15:45 (UTC+0)
apaskulin
added a comment.
Edited
Nov 10 2023, 6:23 PM
2023-11-10 18:23:02 (UTC+0)
Comment Actions
@Krinkle
, the
quickstart doc
is ready for your review. Feel free to leave comments here or on the talk page.
Krinkle
added a comment.
Nov 13 2023, 10:40 PM
2023-11-13 22:40:59 (UTC+0)
Comment Actions
@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.
apaskulin
updated the task description.
(Show Details)
Nov 18 2023, 1:17 AM
2023-11-18 01:17:43 (UTC+0)
apaskulin
added a comment.
Nov 18 2023, 1:25 AM
2023-11-18 01:25:54 (UTC+0)
Comment Actions
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 mediawiki.org Village Pump.
apaskulin
mentioned this in
T347347: Make "Quickstart" MW install a thing
Nov 21 2023, 10:34 PM
2023-11-21 22:34:55 (UTC+0)
apaskulin
added a comment.
Nov 21 2023, 11:10 PM
2023-11-21 23:10:34 (UTC+0)
Comment Actions
I'll be requesting broader feedback on the parent task and the mediawiki.org Village Pump.
This is now done both
on wiki
and
T347347#9351046
TBurmeister
awarded a token.
Nov 30 2023, 8:20 PM
2023-11-30 20:20:59 (UTC+0)
apaskulin
updated the task description.
(Show Details)
Dec 20 2023, 11:24 PM
2023-12-20 23:24:48 (UTC+0)
Comment Actions
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.
kostajh
awarded a token.
Dec 22 2023, 9:26 AM
2023-12-22 09:26:38 (UTC+0)
apaskulin
updated the task description.
(Show Details)
Jan 19 2024, 4:32 AM
2024-01-19 04:32:31 (UTC+0)
apaskulin
closed this task as
Resolved
Jan 20 2024, 2:09 AM
2024-01-20 02:09:29 (UTC+0)
Comment Actions
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.
gerritbot
added a comment.
Jan 22 2024, 1:36 PM
2024-01-22 13:36:47 (UTC+0)
Comment Actions
Change 992164 had a related patch set uploaded (by Ladsgroup; author: Amir Sarabadani):
[mediawiki/core@master] docs: Link to "Local development quickstart" in README
gerritbot
added a project:
Patch-For-Review
Jan 22 2024, 1:36 PM
2024-01-22 13:36:48 (UTC+0)
Ladsgroup
added a comment.
Jan 22 2024, 1:37 PM
2024-01-22 13:37:09 (UTC+0)
Comment Actions
Something to consider ^
gerritbot
added a comment.
Jan 22 2024, 4:28 PM
2024-01-22 16:28:53 (UTC+0)
Comment Actions
Change 992164
merged
by jenkins-bot:
[mediawiki/core@master] docs: Link to "Local development quickstart" in README
Maintenance_bot
removed a project:
Patch-For-Review
Jan 22 2024, 4:31 PM
2024-01-22 16:31:38 (UTC+0)
ReleaseTaggerBot
added a project:
MW-1.42-notes (1.42.0-wmf.15; 2024-01-23)
Jan 22 2024, 5:00 PM
2024-01-22 17:00:42 (UTC+0)
apaskulin
added a comment.
Jan 23 2024, 1:51 AM
2024-01-23 01:51:47 (UTC+0)
Comment Actions
Awesome! Thanks,
@Ladsgroup
KBach
moved this task from
Active projects
to
Done
on the
Tech-Docs-Team
board.
Feb 8 2024, 10:52 AM
2024-02-08 10:52:02 (UTC+0)
Log In to Comment
Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct.
Wikimedia Foundation
Code of Conduct
Disclaimer
CC-BY-SA
GPL
Credits